feat: add account/egress/get capability definition

.nx/version-plans/version-plan-1769007491408.md

@@ -0,0 +1,5 @@
+---
+'@storacha/capabilities': minor
+---
+
+add 'account/egress/get' capability

packages/capabilities/src/account/egress.js

@@ -0,0 +1,62 @@
+import { capability, fail, ok, Schema } from '@ucanto/validator'
+import {
+  AccountDID,
+  SpaceDID,
+  equalWith,
+  and,
+  equal,
+  containedWithin,
+} from '../utils.js'
+
+/**
+ * Capability can only be delegated (but not invoked) allowing audience to
+ * be derived any `account/egress/` prefixed capability for the account identified
+ * by DID in the `with` field.
+ */
+export const accountEgress = capability({
+  can: 'account/egress/*',
+  with: AccountDID,
+  derives: equalWith,
+})
+
+/**
+ * Capability can be invoked by an agent to retrieve egress data for all or a
+ * specified set of spaces within an account in a given period.
+ */
+export const get = capability({
+  can: 'account/egress/get',
+  with: AccountDID,
+  nb: Schema.struct({
+    spaces: SpaceDID.array().optional(),
+    /** Period to retrieve egress between. */
+    period: Schema.struct({
+      /** Date-only string in ISO 8601 format (inclusive). */
+      from: Schema.string(),
+      /** Date-only string in ISO 8601 format (exclusive). */
+      to: Schema.string(),
+    }).optional(),
+  }),
+  derives: (child, parent) => {
+    return (
+      and(equalWith(child, parent)) ||
+      and(
+        (() => {
+          if (parent.nb.spaces === undefined) {
+            return ok({})
+          }
+          if (child.nb.spaces === undefined) {
+            return fail(
+              `Constraint violation: violates imposed spaces constraint ${parent.nb.spaces} because it asks for all spaces`
+            )
+          }
+          return containedWithin(child.nb.spaces, parent.nb.spaces, 'spaces')
+        })()
+      ) ||
+      and(
+        equal(child.nb.period?.from, parent.nb.period?.from, 'period.from')
+      ) ||
+      and(equal(child.nb.period?.to, parent.nb.period?.to, 'period.to')) ||
+      ok({})
+    )
+  },
+})

packages/capabilities/src/index.js

@@ -27,6 +27,7 @@ import * as SpaceBlob from './space/blob.js'
 import * as W3sBlob from './web3.storage/blob.js'
 import * as HTTP from './http.js'
 import * as AccountUsage from './account/usage.js'
+import * as AccountEgress from './account/egress.js'
 import * as PDP from './pdp.js'
 
 export {
@@ -59,6 +60,7 @@ export {
   W3sBlob,
   HTTP,
   AccountUsage,
+  AccountEgress,
   PDP,
 }
 
@@ -132,6 +134,7 @@ export const abilitiesAsStrings = [
   SpaceIndex.index.can,
   SpaceIndex.add.can,
   AccountUsage.get.can,
+  AccountEgress.get.can,
   PDP.accept.can,
   PDP.info.can,
 ]

packages/capabilities/src/types.ts

@@ -45,6 +45,7 @@ import * as UCANCaps from './ucan.js'
 import * as PlanCaps from './plan.js'
 import * as UsageCaps from './usage.js'
 import * as AccountUsageCaps from './account/usage.js'
+import * as AccountEgressCaps from './account/egress.js'
 import * as PDPCaps from './pdp.js'
 
 export type ISO8601Date = string
@@ -259,6 +260,49 @@ export interface SpaceEgressUsage {
   providers: Record<ProviderDID, EgressUsageData>
 }
 
+// AccountEgress
+export type AccountEgress = InferInvokedCapability<
+  typeof AccountEgressCaps.accountEgress
+>
+export type AccountEgressGet = InferInvokedCapability<
+  typeof AccountEgressCaps.get
+>
+
+export interface AccountNotFoundError extends Ucanto.Failure {
+  name: 'AccountNotFound'
+}
+
+export interface SpaceUnauthorizedError extends Ucanto.Failure {
+  name: 'SpaceUnauthorized'
+}
+
+export interface PeriodNotAcceptableError extends Ucanto.Failure {
+  name: 'PeriodNotAcceptable'
+}
+
+export type AccountEgressGetFailure = AccountNotFoundError | SpaceUnauthorizedError | PeriodNotAcceptableError | Ucanto.Failure
+
+export interface AccountEgressGetSuccess {
+  // total egress across all spaces in the period in bytes
+  total: number
+  // breakdown by space
+  spaces: Record<SpaceDID, SpaceEgress>
+}
+
+export interface SpaceEgress {
+  // total egress for the space in the period
+  total: number
+  // daily egress stats
+  dailyStats: DailyStats[]
+}
+
+export interface DailyStats {
+  // date the stats refer to
+  date: ISO8601Date
+  // egress for the day in bytes
+  egress: number
+}
+
 // Provider
 export type ProviderAdd = InferInvokedCapability<typeof provider.add>
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
@@ -1240,6 +1284,8 @@ export type ServiceAbilityArray = [
   SpaceIndexAdd['can'],
   AccountUsage['can'],
   AccountUsageGet['can'],
+  AccountEgress['can'],
+  AccountEgressGet['can'],
   PDPAccept['can'],
   PDPInfo['can']
 ]