better-supabase 0.11.0 → 0.13.0

package/dist/blocks/vercel-marketplace/index.d.ts

@@ -1,12 +1,167 @@
 /// <reference lib="esnext.temporal" />
-import { T as ErrorMapper, t as AsyncResult } from "../../result-BREt7qOh.js";
-import { wt as Events } from "../../events-P3raDX2E.js";
+import { T as ErrorMapper, b as DbError, t as AsyncResult } from "../../result-mijqfoJN.js";
+import { wt as Events } from "../../events-DhGgwqQA.js";
 import { n as Logger } from "../../logger-DWVYUmwi.js";
-import { s as sqlTransport, t as BlockTransport } from "../../block-transport-DezJPPA0.js";
-import { r as BlockTemporalOptions } from "../../block-helpers-CjcQM1yA.js";
-import { n as BlockHooks } from "../../block-hooks-DcPJHztl.js";
-import { s as BlockOf } from "../../define-block-CPyJ95rq.js";
-import { n as Jwks } from "../../jws-35a8VhFV.js";
+import { s as sqlTransport, t as BlockTransport } from "../../block-transport-DBPhgF3W.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-DyA5BAW4.js";
+import { n as BlockHooks } from "../../block-hooks-BadAniNI.js";
+import { a as ProblemFormat, t as BlockProblemOptions } from "../../problem-D_DEBfMn.js";
+import { s as BlockOf } from "../../define-block-MyM4lH42.js";
+import { n as Jwks } from "../../jws-D0toeQlA.js";
+//#region src/blocks/vercel-marketplace/partner-api.d.ts
+/** The Vercel environments a resource's secrets reach. */
+type VercelEnvironment = "production" | "preview" | "development";
+export declare const VERCEL_ENVIRONMENTS: readonly VercelEnvironment[];
+/**
+ * A secret Vercel turns into an environment variable of the projects that use
+ * the resource.
+ */
+interface MarketplaceSecret {
+  readonly name: string;
+  readonly value: string;
+  readonly prefix?: string;
+  /**
+   * A different value per Vercel environment, such as a tenant environment
+   * each.
+   */
+  readonly environmentOverrides?: Readonly<Partial<Record<VercelEnvironment, string>>>;
+  /**
+   * The app's handle for the secret, such as an API key id. The block keeps it
+   * (never the value) so a rotation can revoke the previous secret; Vercel
+   * never sees it.
+   */
+  readonly ref?: string;
+}
+/** A billing plan, as `GET /v1/products/{id}/plans` returns it. */
+interface MarketplacePlan {
+  readonly id: string;
+  readonly name: string;
+  readonly type: "subscription" | "prepayment";
+  readonly scope?: "installation" | "resource";
+  readonly description?: string;
+  readonly paymentMethodRequired?: boolean;
+  readonly details?: readonly {
+    readonly label: string;
+    readonly value?: string;
+  }[];
+  /** The priced items; a free plan has none. */
+  readonly billing?: {
+    readonly items: readonly unknown[];
+  };
+  readonly [field: string]: unknown;
+}
+/** The resource Vercel asks the app to provision. */
+interface MarketplaceResourceRequest {
+  readonly id: string;
+  readonly productId: string | undefined;
+  readonly name: string;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly billingPlanId: string | undefined;
+}
+interface MarketplaceProvisionInput {
+  readonly installation: MarketplaceInstallation;
+  readonly resource: MarketplaceResourceRequest;
+  readonly plan: MarketplacePlan | undefined;
+  /**
+   * Every Vercel environment, for an app that keeps one tenant environment per
+   * Vercel environment.
+   */
+  readonly environments: readonly VercelEnvironment[];
+}
+interface MarketplaceProvisionResult {
+  /** The app's tenant for the resource. */
+  readonly tenant?: string;
+  /**
+   * Whether the hook created the tenant, so deleting the resource may delete
+   * it.
+   */
+  readonly tenantCreated?: boolean;
+  readonly secrets: readonly MarketplaceSecret[];
+}
+interface MarketplaceResourceHooks {
+  /** Creates what the resource stands for and returns its secrets. */
+  provision(input: MarketplaceProvisionInput): Promise<MarketplaceProvisionResult>;
+  /** Applies a rename, new metadata or a plan change. */
+  update?(input: {
+    readonly installation: MarketplaceInstallation;
+    readonly resource: MarketplaceResource;
+    readonly changes: {
+      readonly name?: string;
+      readonly metadata?: Readonly<Record<string, unknown>>;
+      readonly billingPlanId?: string;
+    };
+  }): Promise<void>;
+  /** Tears the resource down, before its tenant is removed. */
+  deprovision?(input: {
+    readonly installation: MarketplaceInstallation;
+    readonly resource: MarketplaceResource;
+  }): Promise<void>;
+  /** Issues new secrets. `revoke` runs only after this resolves. */
+  rotate?(input: {
+    readonly installation: MarketplaceInstallation;
+    readonly resource: MarketplaceResource;
+    readonly reason: string | undefined;
+  }): Promise<{
+    readonly secrets: readonly MarketplaceSecret[];
+  }>;
+  /**
+   * Revokes the secrets a rotation replaced, by the `ref` they were handed out
+   * with.
+   */
+  revoke?(input: {
+    readonly installation: MarketplaceInstallation;
+    readonly resource: MarketplaceResource;
+    readonly previous: readonly string[];
+    /** Hours Vercel asked to keep the old secrets valid. */
+    readonly delayHours: number | undefined;
+  }): Promise<void>;
+}
+interface MarketplaceTenantRemoval {
+  readonly installation: MarketplaceInstallation;
+  readonly tenant: string;
+  /** Whether the installation or the provision hook created the tenant. */
+  readonly created: boolean;
+}
+/** The part of the organizations block the default `removeTenant` uses. */
+interface MarketplaceOrganizations {
+  delete(organizationId: string): AsyncResult<boolean>;
+  members(organizationId: string): AsyncResult<readonly unknown[]>;
+}
+interface PartnerApiOptions extends BlockProblemOptions {
+  readonly resources: MarketplaceResourceHooks;
+  /**
+   * Runs after `PUT /v1/installations/{id}` stored the installation; may link a
+   * tenant.
+   */
+  readonly install?: (input: {
+    readonly installation: MarketplaceInstallation;
+    readonly account: Readonly<Record<string, unknown>>;
+    readonly scopes: readonly string[];
+  }) => Promise<{
+    readonly tenant?: string;
+    readonly tenantCreated?: boolean;
+  } | undefined | void>;
+  /**
+   * Removes a tenant when its resource or installation goes away. Default:
+   * deletes it through `organizations` when the installation created it and it
+   * has no members, and does nothing without `organizations`.
+   */
+  readonly removeTenant?: (input: MarketplaceTenantRemoval) => Promise<void>;
+  readonly organizations?: MarketplaceOrganizations;
+  /**
+   * The plans the integration sells, or a function of the product and
+   * installation.
+   */
+  readonly plans?: readonly MarketplacePlan[] | ((input: {
+    readonly productId: string | undefined;
+    readonly installation: MarketplaceInstallation | undefined;
+  }) => Promise<readonly MarketplacePlan[]>);
+  /** New resource ids for `POST .../resources`. Default: `crypto.randomUUID()`. */
+  readonly resourceId?: () => string;
+  /** Include the messages of internal errors in responses. Default: false. */
+  readonly expose?: boolean;
+}
+//#endregion
 //#region src/blocks/vercel-marketplace/vercel-marketplace.d.ts
 /** An installation of the integration by a Vercel team. */
 interface MarketplaceInstallation {
@@ -16,6 +171,11 @@ interface MarketplaceInstallation {
   readonly userId: string | undefined;
   /** The app's own tenant for this installation, once the app linked one. */
   readonly tenant: string | undefined;
+  /**
+   * Whether the installation created its tenant, so removing it may delete the
+   * tenant.
+   */
+  readonly tenantCreated: boolean;
   readonly status: "active" | "suspended" | "removed";
   readonly metadata: Readonly<Record<string, unknown>>;
 }
@@ -28,6 +188,14 @@ interface MarketplaceResource {
   readonly planId: string | undefined;
   readonly status: "pending" | "ready" | "suspended" | "deleted";
   readonly metadata: Readonly<Record<string, unknown>>;
+  /** The app's tenant the provision hook created or chose. */
+  readonly tenant: string | undefined;
+  readonly tenantCreated: boolean;
+  /**
+   * The app's handles for the secrets handed out, for the next rotation's
+   * revoke.
+   */
+  readonly secretRefs: readonly string[];
 }
 interface MarketplaceInvoice {
   readonly id: string;
@@ -42,7 +210,12 @@ interface MeterReport {
   readonly installationId: string;
   readonly resourceExternalId: string;
   readonly meterId: string;
+  readonly periodStart: string;
+  readonly periodEnd: string;
+  /** The period's total so far. */
   readonly quantity: number;
+  /** The total Vercel accepted; the next report sends the rest as `dayValue`. */
+  readonly reportedQuantity: number;
   readonly reported: boolean;
 }
 /** What a verified Vercel webhook did. */
@@ -64,18 +237,25 @@ interface MarketplaceSsoClaims {
 interface VercelMarketplaceOptions extends BlockTemporalOptions {
   /** A service-role transport: every function is granted to `service_role` only. */
   readonly transport: BlockTransport;
-  /** The integration's client secret: signs webhooks and authenticates the SSO exchange. */
+  /**
+   * The integration's client secret: signs webhooks and authenticates the SSO
+   * exchange.
+   */
   readonly clientSecret: string;
   /** The integration's client id, for the SSO exchange and the `aud` claim. */
   readonly clientId: string;
   /**
    * A bearer token for the Marketplace API on behalf of an installation, for
-   * invoices and usage. Vercel hands it out at installation; the app stores it.
+   * invoices and usage. Default: the token Vercel handed out at installation,
+   * which the Partner API seals in Vault.
    */
   readonly accessToken?: (configurationId: string) => Promise<string>;
   readonly schema?: string;
   readonly mappers?: readonly ErrorMapper[];
-  /** `withBlockHooks` hooks around the client's methods, such as a check before a resource is provisioned. */
+  /**
+   * `withBlockHooks` hooks around the client's methods, such as a check before
+   * a resource is provisioned.
+   */
   readonly hooks?: BlockHooks<VercelMarketplace>;
   /** Receives the errors `after` hooks throw. Default: `console`. */
   readonly logger?: Logger;
@@ -116,12 +296,26 @@ interface ReportUsageInput {
     readonly resourceId?: string;
   }[];
 }
+interface UsageRouteOptions {
+  /** The bearer token the cron caller sends, such as `process.env.CRON_SECRET`. */
+  readonly secret: string | undefined;
+  /** The period totals to report, one entry per installation. */
+  readonly usage: () => Promise<readonly ReportUsageInput[]>;
+  readonly onError?: (error: DbError, configurationId: string) => void;
+  readonly problem?: ProblemFormat;
+}
 interface VercelMarketplace {
-  /** Whether `signature` is the HMAC-SHA1 of the raw body under the client secret. */
+  /**
+   * Whether `signature` is the HMAC-SHA1 of the raw body under the client
+   * secret.
+   */
   verifyWebhook(body: string, signature: string | null): Promise<boolean>;
   /** Verifies a webhook request and applies it: removals and invoice states. */
   handleWebhook(request: Request): AsyncResult<MarketplaceWebhookResult>;
-  /** Exchanges the SSO `code`, verifies the `id_token` and keeps the installation current. */
+  /**
+   * Exchanges the SSO `code`, verifies the `id_token` and keeps the
+   * installation current.
+   */
   exchangeSso(input: {
     readonly code: string;
     readonly state?: string;
@@ -155,16 +349,54 @@ interface VercelMarketplace {
     readonly id: string;
   }>;
   /**
-   * Stores the quantities, then sends the ones Vercel has not accepted yet.
-   * A failed send leaves them stored, so the next call retries them.
+   * Stores the period totals, then sends what Vercel has not accepted yet, one
+   * request per billing period: `periodValue` is the total and `dayValue` the
+   * part not reported before. A failed send leaves the rest stored, so the next
+   * call resends it.
    */
   reportUsage(input: ReportUsageInput): AsyncResult<readonly MeterReport[]>;
+  /**
+   * Marks the installation removed and its resources deleted, and drops its
+   * sealed token.
+   */
+  removeInstallation(configurationId: string): AsyncResult<MarketplaceInstallation | undefined>;
+  /** Seals the installation's access token in Vault. */
+  sealAccessToken(configurationId: string, token: string): AsyncResult<void>;
+  /**
+   * Links the app's tenant to an installation; `created` lets removal delete
+   * it.
+   */
+  linkTenant(input: {
+    readonly configurationId: string;
+    readonly tenant: string;
+    readonly created?: boolean;
+  }): AsyncResult<MarketplaceInstallation>;
+  resource(configurationId: string, externalId: string): AsyncResult<MarketplaceResource | undefined>;
+  /** The installation's resources that are not deleted. */
+  resources(configurationId: string): AsyncResult<readonly MarketplaceResource[]>;
+  /** Marks a resource deleted; the row stays for invoices and audit. */
+  deleteResource(configurationId: string, externalId: string): AsyncResult<MarketplaceResource | undefined>;
+  /**
+   * The Partner API Vercel calls (installations, resources, secret rotation and
+   * plans) as one `Request` to `Response` handler, every request checked
+   * against Vercel's OIDC token.
+   */
+  partnerApi(options: PartnerApiOptions): (request: Request) => Promise<Response>;
+  /**
+   * A cron route that reports the totals `usage` returns. It answers 200 with
+   * the configuration ids it reported, or 502 when one failed; the failed ones
+   * are sent again on the next run.
+   */
+  usageRoute(options: UsageRouteOptions): (request: Request) => Promise<Response>;
 }
 /** Vercel Marketplace provider state, webhooks, SSO and billing. */
 export declare function createVercelMarketplace(options: VercelMarketplaceOptions): VercelMarketplace;
 //#endregion
 //#region src/blocks/vercel-marketplace/events.d.ts
-/** `marketplace_installation.*`: the Vercel team's installation of the integration. */
+/**
+ * `marketplace_installation.*`: the Vercel team's installation of the
+ * integration.
+ */
 interface MarketplaceInstallationEventData {
   readonly installationId: string;
   readonly configurationId: string;
@@ -183,11 +415,14 @@ type VercelMarketplaceEvents = {
   readonly "marketplace_installation.removed": MarketplaceInstallationEventData;
   readonly "marketplace_invoice.state_changed": MarketplaceInvoiceEventData;
 };
-/** The `vercel-marketplace` block's event types, for its manifest and `onBlockEvent`. */
+/**
+ * The `vercel-marketplace` block's event types, for its manifest and
+ * `onBlockEvent`.
+ */
 export declare const vercelMarketplaceEvents: Events<VercelMarketplaceEvents>;
 //#endregion
 //#region src/blocks/vercel-marketplace/manifest.d.ts
 /** The `vercel-marketplace` block's manifest (ADR 0029). */
 export declare const vercelMarketplaceBlock: BlockOf<"vercel-marketplace", typeof createVercelMarketplace, VercelMarketplaceEvents>;
 //#endregion
-export { type BlockTransport, type InvoiceItem, type MarketplaceInstallation, type MarketplaceInstallationEventData, type MarketplaceInvoice, type MarketplaceInvoiceEventData, type MarketplaceResource, type MarketplaceSsoClaims, type MarketplaceWebhookResult, type MeterReport, type ReportUsageInput, type SubmitInvoiceInput, type VercelMarketplace, type VercelMarketplaceEvents, type VercelMarketplaceOptions, sqlTransport };
+export { type BlockTransport, type InvoiceItem, type MarketplaceInstallation, type MarketplaceInstallationEventData, type MarketplaceInvoice, type MarketplaceInvoiceEventData, type MarketplaceOrganizations, type MarketplacePlan, type MarketplaceProvisionInput, type MarketplaceProvisionResult, type MarketplaceResource, type MarketplaceResourceHooks, type MarketplaceResourceRequest, type MarketplaceSecret, type MarketplaceSsoClaims, type MarketplaceTenantRemoval, type MarketplaceWebhookResult, type MeterReport, type PartnerApiOptions, type ReportUsageInput, type SubmitInvoiceInput, type UsageRouteOptions, type VercelEnvironment, type VercelMarketplace, type VercelMarketplaceEvents, type VercelMarketplaceOptions, sqlTransport };