tapimo 0.13.0 → 0.15.0

package/src/admin/apps/organizations.ts

@@ -4,18 +4,24 @@ import * as z from 'zod/mini'
 import * as Analytics from '../../analytics/Analytics.js'
 import * as ApiKeys from '../../ApiKeys.js'
 import * as core_Billing from '../../apps/management/Billing.js'
+import * as Invitations from '../../apps/management/routes/invitations.js'
+import * as Zones from '../../apps/Zones.js'
 import * as BillingSettings from '../../db/tables/billingSettings.js'
 import * as Db from '../../db/Db.js'
 import * as EnabledBillingSources from '../../db/tables/enabledBillingSources.js'
 import * as Memberships from '../../db/tables/memberships.js'
 import * as Organizations from '../../db/tables/organizations.js'
 import * as Projects from '../../db/tables/projects.js'
+import * as RoutesDeposits from '../../db/tables/routesDeposits.js'
+import * as RoutesSubsidies from '../../db/tables/routesSubsidies.js'
+import * as RoutesTransfers from '../../db/tables/routesTransfers.js'
 import * as SponsoredTransactions from '../../db/tables/sponsoredTransactions.js'
 import * as StripeCustomers from '../../db/tables/stripeCustomers.js'
 import * as WebhookDeliveries from '../../db/tables/webhookDeliveries.js'
 import * as WebhookSubscriptions from '../../db/tables/webhookSubscriptions.js'
 import * as Cursor from '../../internal/Cursor.js'
 import * as OpenApi from '../../internal/OpenApi.js'
+import * as RateLimit from '../../internal/RateLimit.js'
 import * as Response from '../../internal/Response.js'
 import * as Schema from '../../internal/Schema.js'
 import * as Viem from '../../internal/Viem.js'
@@ -71,6 +77,68 @@ export namespace schema {
     'An organization visible to an authenticated administrator.',
   )
 
+  const RoutesSubsidy = z
+    .nullable(
+      z.object({
+        frequency: z
+          .literal('tx')
+          .check(z.describe('Interval over which the subsidy limit applies.'), z.meta({ examples: ['tx'] })), // prettier-ignore
+        maxAmount: z
+          .string()
+          .check(
+            z.describe('Maximum Routes subsidy gap in decimal USD.'),
+            z.meta({ examples: ['5'] }),
+          ),
+      }),
+    )
+    .check(
+      z.describe('Current Routes subsidy policy, or null when disabled.'),
+      z.meta({ examples: [{ frequency: 'tx', maxAmount: '5' }] }),
+    )
+
+  const SponsorshipSubsidy = Schema.describe(
+    z.object({
+      attributionSpendLimit: z
+        .nullable(z.string())
+        .check(z.describe('Optional per-attribution promotion cap in USD.'), z.meta({ examples: ['1000'] })), // prettier-ignore
+      durationDays: z
+        .nullable(z.literal(90))
+        .check(z.describe('Promotion duration in days, or null when disabled.'), z.meta({ examples: [90] })), // prettier-ignore
+    }),
+    'Current per-attribution sponsorship subsidy policy.',
+  )
+
+  const RoutesSubsidyUsage = Schema.describe(
+    z.object({
+      amount: z
+        .string()
+        .check(
+          z.describe('Completed production Routes subsidies in decimal USD.'),
+          z.meta({ examples: ['12.5'] }),
+        ),
+      count: z
+        .number()
+        .check(
+          z.int(),
+          z.nonnegative(),
+          z.describe('Completed production Routes subsidies in the window.'),
+          z.meta({ examples: [4] }),
+        ),
+      from: timestamp,
+      to: timestamp,
+    }),
+    'Current-month production Routes subsidy usage.',
+  )
+
+  const Subsidies = Schema.describe(
+    z.object({
+      routes: RoutesSubsidy,
+      routesUsage: RoutesSubsidyUsage,
+      sponsorship: SponsorshipSubsidy,
+    }),
+    'Current organization subsidy policies.',
+  )
+
   /** Schemas for the listOrganizations operation. */
   export namespace listOrganizations {
     /** Query parameters for organization lookup. */
@@ -292,6 +360,12 @@ export namespace schema {
     )
   }
 
+  /** Schemas for reading organization subsidy policies. */
+  export namespace getOrganizationSubsidies {
+    /** Current organization subsidy policies. */
+    export const Response = Subsidies
+  }
+
   /** Schemas for the setBillingSource operation. */
   export namespace setBillingSource {
     /** Path parameters identifying an organization billing source. */
@@ -435,8 +509,8 @@ export namespace schema {
     )
   }
 
-  /** Schemas for the getOrganizationSponsorship operation. */
-  export namespace getOrganizationSponsorship {
+  /** Schemas for organization sponsorship operations. */
+  export namespace organizationSponsorship {
     const Environment = z.object({
       committedSpend: z
         .string()
@@ -454,7 +528,7 @@ export namespace schema {
     })
 
     /** Current-period sponsorship spend by key environment. */
-    export const Response = Schema.describe(
+    export const GetResponse = Schema.describe(
       z.object({
         production: Environment,
         sandbox: Environment,
@@ -464,6 +538,57 @@ export namespace schema {
     )
   }
 
+  /** Schemas for setting an organization Routes subsidy policy. */
+  export namespace setOrganizationRoutesSubsidy {
+    /** Replacement Routes subsidy policy. */
+    export const Body = z
+      .union([
+        z.object({ enabled: z.literal(false) }),
+        z.object({
+          enabled: z.literal(true),
+          frequency: z
+            .literal('tx')
+            .check(z.describe('Interval over which the subsidy limit applies.'), z.meta({ examples: ['tx'] })), // prettier-ignore
+          maxAmount: z
+            .string()
+            .check(
+              z.regex(/^(?!0(?:\.0{1,6})?$)(?:0|[1-9]\d*)(?:\.\d{1,6})?$/),
+              z.describe('Maximum Routes subsidy gap in decimal USD.'),
+              z.meta({ examples: ['5'] }),
+            ),
+        }),
+      ])
+      .check(z.describe('Replacement organization Routes subsidy policy.'))
+
+    /** Current Routes subsidy policy. */
+    export const Response = RoutesSubsidy
+  }
+
+  /** Schemas for setting an organization sponsorship subsidy policy. */
+  export namespace setOrganizationSponsorshipSubsidy {
+    /** Replacement sponsorship subsidy policy. */
+    export const Body = z
+      .union([
+        z.object({
+          attributionSpendLimit: z.optional(
+            z
+              .string()
+              .check(
+                z.regex(/^(?:0|[1-9]\d*)(?:\.\d{1,6})?$/),
+                z.describe('Optional per-attribution promotion cap in USD.'),
+                z.meta({ examples: ['1000'] }),
+              ),
+          ),
+          enabled: z.literal(true),
+        }),
+        z.object({ enabled: z.literal(false) }),
+      ])
+      .check(z.describe('Replacement per-attribution sponsorship subsidy policy.'))
+
+    /** Current sponsorship subsidy policy. */
+    export const Response = SponsorshipSubsidy
+  }
+
   /** Schemas for the getOrganizationWebhooks operation. */
   export namespace getOrganizationWebhooks {
     const Failure = z.object({
@@ -648,6 +773,162 @@ export function organizations() {
         }
       },
     )
+    .get(
+      '/:orgId/subsidies',
+      OpenApi.validate('param', schema.getOrganization.Params, {
+        code: 'param_invalid',
+        message: 'Invalid path parameters',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'getAdminOrganizationSubsidies',
+        responses: OpenApi.responses({
+          errors: { 404: 'Organization not found.' },
+          success: {
+            description: 'Current organization subsidy policies.',
+            schema: schema.getOrganizationSubsidies.Response,
+          },
+        }),
+        summary: 'Get subsidies',
+        tags: ['Organizations'],
+      }),
+      async (c) => {
+        const { orgId } = c.req.valid('param')
+        const db = Db.get(c.get('db'))
+        try {
+          const now = new Date()
+          const from = core_Billing.periodStart('month', now)
+          const to = now.toISOString()
+          const [depositUsage, organization, routes, transferUsage] = await Promise.all([
+            RoutesDeposits.subsidyUsage(db, { environment: 'production', from, orgId, to }),
+            Organizations.get(db, orgId),
+            RoutesSubsidies.getOrganization(db, orgId),
+            RoutesTransfers.subsidyUsage(db, { environment: 'production', from, orgId, to }),
+          ])
+          if (!organization) return organizationNotFound(c)
+          return c.json(
+            Response.validated(schema.getOrganizationSubsidies.Response, {
+              routes:
+                routes?.enabled && routes.maxAmount !== null
+                  ? { frequency: routes.frequency, maxAmount: routes.maxAmount }
+                  : null,
+              routesUsage: {
+                amount: core_Billing.fromBaseUnits(depositUsage.amount + transferUsage.amount),
+                count: depositUsage.count + transferUsage.count,
+                from,
+                to,
+              },
+              sponsorship: {
+                attributionSpendLimit: organization.sponsorshipSubsidyProjectSpendLimit,
+                durationDays: organization.sponsorshipSubsidyDurationDays,
+              },
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .put(
+      '/:orgId/subsidies/routes',
+      OpenApi.validate('param', schema.getOrganization.Params, {
+        code: 'param_invalid',
+        message: 'Invalid path parameters',
+      }),
+      OpenApi.validate('json', schema.setOrganizationRoutesSubsidy.Body, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'setAdminOrganizationRoutesSubsidy',
+        responses: OpenApi.responses({
+          errors: { 404: 'Organization not found.' },
+          success: {
+            description: 'Current Routes subsidy policy.',
+            schema: schema.setOrganizationRoutesSubsidy.Response,
+          },
+        }),
+        summary: 'Set Routes subsidy',
+        tags: ['Organizations'],
+      }),
+      async (c) => {
+        const { orgId } = c.req.valid('param')
+        const policy = c.req.valid('json')
+        const db = Db.get(c.get('db'))
+        try {
+          const organization = await Organizations.get(db, orgId)
+          if (!organization) return organizationNotFound(c)
+          const subsidy = await (async () => {
+            if (!policy.enabled) {
+              await RoutesSubsidies.removeOrganization(db, orgId)
+              return undefined
+            }
+            return RoutesSubsidies.upsertOrganization(db, {
+              frequency: policy.frequency,
+              maxAmount: policy.maxAmount,
+              orgId,
+            })
+          })()
+          return c.json(
+            Response.validated(
+              schema.setOrganizationRoutesSubsidy.Response,
+              subsidy?.enabled && subsidy.maxAmount !== null
+                ? { frequency: subsidy.frequency, maxAmount: subsidy.maxAmount }
+                : null,
+            ),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
+    .put(
+      '/:orgId/subsidies/sponsorship',
+      OpenApi.validate('param', schema.getOrganization.Params, {
+        code: 'param_invalid',
+        message: 'Invalid path parameters',
+      }),
+      OpenApi.validate('json', schema.setOrganizationSponsorshipSubsidy.Body, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'setAdminOrganizationSponsorshipSubsidy',
+        responses: OpenApi.responses({
+          errors: { 404: 'Organization not found.' },
+          success: {
+            description: 'Current sponsorship subsidy policy.',
+            schema: schema.setOrganizationSponsorshipSubsidy.Response,
+          },
+        }),
+        summary: 'Set sponsorship subsidy',
+        tags: ['Organizations'],
+      }),
+      async (c) => {
+        const { orgId } = c.req.valid('param')
+        const policy = c.req.valid('json')
+        try {
+          const organization = await Organizations.setSponsorshipSubsidy(
+            Db.get(c.get('db')),
+            orgId,
+            policy.enabled
+              ? { attributionSpendLimit: policy.attributionSpendLimit ?? null, durationDays: 90 }
+              : { attributionSpendLimit: null, durationDays: null },
+          )
+          if (!organization) return organizationNotFound(c)
+          return c.json(
+            Response.validated(schema.setOrganizationSponsorshipSubsidy.Response, {
+              attributionSpendLimit: organization.sponsorshipSubsidyProjectSpendLimit,
+              durationDays: organization.sponsorshipSubsidyDurationDays,
+            }),
+            200,
+          )
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .put(
       '/:orgId/billing-sources/:source',
       OpenApi.validate('param', schema.setBillingSource.Params, {
@@ -778,6 +1059,61 @@ export function organizations() {
         }
       },
     )
+    .post(
+      '/:orgId/invitations',
+      OpenApi.validate('param', Invitations.schema.Params, {
+        code: 'param_invalid',
+        message: 'Invalid path parameters',
+      }),
+      OpenApi.validate('json', Invitations.schema.CreateInvitationRequest, {
+        code: 'body_invalid',
+        message: 'Invalid request body',
+      }),
+      OpenApi.describeRoute({
+        operationId: 'createAdminOrganizationInvitation',
+        responses: OpenApi.responses({
+          errors: {
+            404: 'Organization not found.',
+            429: 'The invitation email rate limit was exceeded.',
+          },
+          success: {
+            description: 'The created organization invitation.',
+            schema: Invitations.schema.Invitation,
+          },
+        }),
+        summary: 'Invite organization member',
+        tags: ['Organizations'],
+      }),
+      async (c) => {
+        const { orgId } = c.req.valid('param')
+        const body = c.req.valid('json')
+        const db = Db.get(c.get('db'))
+        try {
+          const organization = await Organizations.get(db, orgId)
+          if (!organization) return organizationNotFound(c)
+          const invitationEmail = c.get('email')
+          const limited = await Invitations.consumeEmailRateLimit({
+            email: body.email,
+            enabled: !!invitationEmail,
+            metrics: c.get('metrics'),
+            rateLimit: c.get('rateLimit'),
+          })
+          if (limited) return invitationRateLimitError(c, limited)
+          const record = await Invitations.createInvitation({
+            db,
+            email: body.email,
+            invitationEmail,
+            invitedBy: 'super_admin',
+            org: organization,
+            role: body.role,
+            waitUntil: (promise) => c.executionCtx.waitUntil(promise),
+          })
+          return c.json(Response.validated(Invitations.schema.Invitation, record), 200)
+        } catch (cause) {
+          return Response.upstream(c, cause)
+        }
+      },
+    )
     .get(
       '/:orgId/projects',
       OpenApi.validate('param', schema.getOrganization.Params, {
@@ -933,7 +1269,7 @@ export function organizations() {
           errors: { 404: 'Organization not found.' },
           success: {
             description: 'Recent organization sponsorship activity.',
-            schema: schema.getOrganizationSponsorship.Response,
+            schema: schema.organizationSponsorship.GetResponse,
           },
         }),
         summary: 'Get sponsorship activity',
@@ -953,9 +1289,11 @@ export function organizations() {
               const period = settings?.period ?? 'month'
               const from = core_Billing.periodStart(period, now)
               const committedSpend = await SponsoredTransactions.spend(db, {
-                chainIds: [
-                  environment === 'production' ? Viem.chainId.mainnet : Viem.chainId.testnet,
-                ],
+                chainIds: Zones.chainIds({
+                  sourceId:
+                    environment === 'production' ? Viem.chainId.mainnet : Viem.chainId.testnet,
+                  zones: c.get('zones'),
+                }),
                 environment,
                 orgId,
                 since: from,
@@ -969,7 +1307,7 @@ export function organizations() {
             }),
           )
           return c.json(
-            Response.validated(schema.getOrganizationSponsorship.Response, {
+            Response.validated(schema.organizationSponsorship.GetResponse, {
               production,
               sandbox,
               to,
@@ -1038,6 +1376,28 @@ export function organizations() {
     )
 }
 
+function invitationRateLimitError(
+  c: Context<App.Environment>,
+  limited: {
+    /** Denied quota result. */
+    result: RateLimit.Result
+    /** Quota dimension that denied the request. */
+    scope: string
+  },
+) {
+  const { result, scope } = limited
+  c.header('RateLimit-Limit', String(result.limit))
+  c.header('RateLimit-Remaining', String(result.remaining))
+  c.header('RateLimit-Reset', String(result.reset))
+  c.header('RateLimit-Scope', scope)
+  c.header('Retry-After', String(Math.max(result.reset - Math.ceil(Date.now() / 1_000), 1)))
+  return Response.error(c, {
+    code: 'rate_limit_exceeded',
+    message: 'Rate limit exceeded',
+    status: 429,
+  })
+}
+
 const usagePeriods = {
   '24h': 24 * 60 * 60 * 1_000,
   '30d': 30 * 24 * 60 * 60 * 1_000,

package/src/admin/apps/routes-support.test.ts

@@ -0,0 +1,200 @@
+import * as TestAdmin from '../../../test/Admin.js'
+import * as TestApp from '../../../test/App.js'
+import * as RoutesCatalog from '../../internal/routes/Catalog.js'
+import * as RoutesSupport from './routes-support.js'
+
+const catalog = {
+  chains: [
+    {
+      aliases: ['eth'],
+      id: 'eip155:1',
+      name: 'Ethereum',
+      parentChainId: null,
+      rpcUrls: ['https://ethereum.example'],
+      slug: 'ethereum',
+    },
+    {
+      aliases: [],
+      id: 'eip155:4217',
+      name: 'Tempo',
+      parentChainId: null,
+      rpcUrls: ['https://tempo.example'],
+      slug: 'tempo',
+    },
+  ],
+  chainTokens: [
+    {
+      address: '0xA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48',
+      chainId: 'eip155:1',
+      decimals: 6,
+      name: null,
+      standard: 'ERC-20',
+      tokenId: 'usdc',
+    },
+    {
+      address: '0x20C000000000000000000000B9537D11C60E8B50',
+      chainId: 'eip155:4217',
+      decimals: 6,
+      name: null,
+      standard: 'TIP-20',
+      tokenId: 'usdce',
+    },
+  ],
+  routes: [
+    {
+      capabilities: { depositAddress: true },
+      destinationChainId: 'eip155:4217',
+      destinationTokenId: 'usdce',
+      providerId: 'relay',
+      sourceChainId: 'eip155:1',
+      sourceTokenId: 'usdc',
+    },
+    {
+      destinationChainId: 'eip155:4217',
+      destinationTokenId: 'usdce',
+      providerId: 'rhino',
+      sourceChainId: 'eip155:1',
+      sourceTokenId: 'usdc',
+    },
+    {
+      capabilities: { transfer: { modes: ['exactSource'] } },
+      destinationChainId: 'eip155:4217',
+      destinationTokenId: 'usdce',
+      providerId: 'stargate',
+      sourceChainId: 'eip155:1',
+      sourceTokenId: 'usdc',
+    },
+    {
+      capabilities: { transfer: { modes: ['exactSource'] } },
+      destinationChainId: 'eip155:1',
+      destinationTokenId: 'usdc',
+      providerId: 'stargate',
+      sourceChainId: 'eip155:4217',
+      sourceTokenId: 'usdce',
+    },
+  ],
+  tokens: [
+    { currency: 'USD', id: 'usdc', name: 'USD Coin', symbol: 'USDC' },
+    {
+      currency: 'USD',
+      id: 'usdce',
+      name: 'Bridged USDC (Stargate)',
+      symbol: 'USDC.e',
+    },
+  ],
+} as const satisfies RoutesCatalog.publish.Input
+
+describe('GET /routes/support', () => {
+  test('groups published capabilities and reports conditional subsidy eligibility', async () => {
+    const { app, db } = TestAdmin.setup()
+    const published = await RoutesCatalog.publish(db, catalog)
+    const response = await app.request('/routes/support')
+    const body = await TestApp.json(response, RoutesSupport.schema.getRoutesSupport.Response)
+
+    expect(response.status).toBe(200)
+    expect({ ...body, updatedAt: '<updatedAt>' }).toMatchInlineSnapshot(`
+      {
+        "data": [
+          {
+            "depositAddressProviders": [
+              "relay",
+            ],
+            "destinationChain": {
+              "id": "eip155:4217",
+              "name": "Tempo",
+              "slug": "tempo",
+            },
+            "destinationToken": {
+              "id": "usdce",
+              "name": "Bridged USDC (Stargate)",
+              "symbol": "USDC.e",
+            },
+            "id": "eip155:1/usdc-eip155:4217/usdce",
+            "quoteProviders": [
+              "relay",
+              "rhino",
+              "stargate",
+            ],
+            "sourceChain": {
+              "id": "eip155:1",
+              "name": "Ethereum",
+              "slug": "ethereum",
+            },
+            "sourceToken": {
+              "id": "usdc",
+              "name": "USD Coin",
+              "symbol": "USDC",
+            },
+            "subsidies": {
+              "depositAddress": true,
+              "walletTransfer": false,
+            },
+            "walletTransferProviders": [
+              {
+                "modes": [
+                  "exactSource",
+                ],
+                "providerId": "stargate",
+              },
+            ],
+          },
+          {
+            "depositAddressProviders": [],
+            "destinationChain": {
+              "id": "eip155:1",
+              "name": "Ethereum",
+              "slug": "ethereum",
+            },
+            "destinationToken": {
+              "id": "usdc",
+              "name": "USD Coin",
+              "symbol": "USDC",
+            },
+            "id": "eip155:4217/usdce-eip155:1/usdc",
+            "quoteProviders": [
+              "stargate",
+            ],
+            "sourceChain": {
+              "id": "eip155:4217",
+              "name": "Tempo",
+              "slug": "tempo",
+            },
+            "sourceToken": {
+              "id": "usdce",
+              "name": "Bridged USDC (Stargate)",
+              "symbol": "USDC.e",
+            },
+            "subsidies": {
+              "depositAddress": false,
+              "walletTransfer": true,
+            },
+            "walletTransferProviders": [
+              {
+                "modes": [
+                  "exactSource",
+                ],
+                "providerId": "stargate",
+              },
+            ],
+          },
+        ],
+        "updatedAt": "<updatedAt>",
+      }
+    `)
+    expect(body.updatedAt).toBe(published.updatedAt)
+    expect(response.headers.get('cache-control')).toBe('no-store')
+  })
+
+  test('serves an empty catalog', async () => {
+    const { app } = TestAdmin.setup()
+    const response = await app.request('/routes/support')
+
+    expect(await TestApp.json(response, RoutesSupport.schema.getRoutesSupport.Response))
+      .toMatchInlineSnapshot(`
+      {
+        "data": [],
+        "updatedAt": "1970-01-01T00:00:00.000Z",
+      }
+    `)
+  })
+})