@forgezero/providers 0.1.23 → 0.1.25

package/README.md

@@ -40,12 +40,11 @@ These are supported consumer entry points, not every internal module shipped for
 | @forgezero/providers/database | ArangoDB in the registry for credential rotation and health — with failover off by default. | portable | [Reference + usage](#forgezero-providers-database) |
 | @forgezero/providers/http | Outbound HTTP with a per-host weight budget reserved before the call and settled from the response. | portable | [Reference + usage](#forgezero-providers-http) |
 | @forgezero/providers/pool | Which outbound address a request leaves by, sticky per key, over the same budget as everything else. | portable | [Reference + usage](#forgezero-providers-pool) |
-| @forgezero/providers/chain | An EVM node behind the same failover as any other service: read logs, broadcast, and never stop scanning because one endpoint rate-limited. | portable | [Reference + usage](#forgezero-providers-chain) |
-| @forgezero/providers/binance | Binance behind the venue adapter: three hosts, one weight budget, signed over the exact string that is sent. | portable | [Reference + usage](#forgezero-providers-binance) |
 | @forgezero/providers/storage | S3-compatible object storage, SigV4 signed with Web Crypto and no vendor SDK. | portable | [Reference + usage](#forgezero-providers-storage) |
 | @forgezero/providers/translation | Google AI Studio translation with strict batch alignment and classified quota failures. | portable | [Reference + usage](#forgezero-providers-translation) |
 | @forgezero/providers/realtime | Cloudflare KV node-directory and Durable Object fan-out clients for project-defined realtime services. | portable | [Reference + usage](#forgezero-providers-realtime) |
 | @forgezero/providers/git | Versioned Git Connect contracts for accounts, repositories, branches, webhooks and short-lived clone credentials; GitHub, GitLab and private forges attach without changing the service. | portable | [Reference + usage](#forgezero-providers-git) |
+| @forgezero/providers/billing | Versioned hosted-payment contracts for Stripe, PayPal and Razorpay; only opaque provider references cross the boundary. | portable | [Reference + usage](#forgezero-providers-billing) |
 
 ## Commands
 
@@ -259,52 +258,6 @@ import {
 export const selectedCapability = PoolEmpty;
 ```
 
-<a id="forgezero-providers-chain"></a>
-## @forgezero/providers/chain
-
-An EVM node behind the same failover as any other service: read logs, broadcast, and never stop scanning because one endpoint rate-limited. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
-
-```text
-import {
-  evmRpc,
-} from '@forgezero/providers/chain';
-```
-
-## @forgezero/providers/chain — Use this entry point
-
-This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
-
-```text
-import {
-  evmRpc,
-} from '@forgezero/providers/chain';
-
-export const selectedCapability = evmRpc;
-```
-
-<a id="forgezero-providers-binance"></a>
-## @forgezero/providers/binance
-
-Binance behind the venue adapter: three hosts, one weight budget, signed over the exact string that is sent. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
-
-```text
-import {
-  binanceSymbol,
-} from '@forgezero/providers/binance';
-```
-
-## @forgezero/providers/binance — Use this entry point
-
-This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
-
-```text
-import {
-  binanceSymbol,
-} from '@forgezero/providers/binance';
-
-export const selectedCapability = binanceSymbol;
-```
-
 <a id="forgezero-providers-storage"></a>
 ## @forgezero/providers/storage
 
@@ -381,7 +334,7 @@ Versioned Git Connect contracts for accounts, repositories, branches, webhooks a
 
 ```text
 import {
-  defineGitConnectProvider,
+  defineGitHubProvider,
 } from '@forgezero/providers/git';
 ```
 
@@ -391,10 +344,47 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  defineGitConnectProvider,
+  defineGitHubProvider,
 } from '@forgezero/providers/git';
 
-export const selectedCapability = defineGitConnectProvider;
+export const selectedCapability = defineGitHubProvider;
+```
+
+<a id="forgezero-providers-billing"></a>
+## @forgezero/providers/billing
+
+Versioned hosted-payment contracts for Stripe, PayPal and Razorpay; only opaque provider references cross the boundary. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
+
+```text
+import {
+  PAYMENT_PROVIDER_KEYS,
+} from '@forgezero/providers/billing';
+```
+
+## @forgezero/providers/billing — Bind a reviewed payment-provider API version
+
+ForgeZero receives only hosted setup URLs and opaque provider references. The concrete HTTP driver and its Vault-backed credentials remain at the host boundary.
+
+```text
+import {
+  paymentProviderAdapter,
+  type PaymentProviderDriver,
+} from '@forgezero/providers/billing';
+
+declare const stripeDriver: PaymentProviderDriver;
+const stripe = paymentProviderAdapter({
+  key: 'stripe:v1',
+  providerApiVersion: '2026-08',
+  driver: stripeDriver
+});
+
+const setup = await stripe.createHostedSetup({
+  tenantKey: 'tenant_123',
+  returnUrl: 'https://app.example.com/billing/return',
+  cancelUrl: 'https://app.example.com/billing',
+  idempotencyKey: crypto.randomUUID()
+});
+location.assign(setup.hostedUrl);
 ```
 
 ## Built-in provider capabilities
@@ -402,14 +392,20 @@ export const selectedCapability = defineGitConnectProvider;
 A provider owns versioned capabilities; it does not own a service. A service method attaches an exact provider, method and version in an ordered array. Current, legacy and deprecated branches can coexist; retired branches never run.
 
 ```text
-github-app
-  - listAccounts
+github
+  - beginUserAuthorization
+  - completeUserAuthorization
+  - readVerifiedIdentity
+  - refreshUserGrant
+  - revokeUserGrant
+  - beginInstallation
+  - completeInstallation
+  - listInstallations
   - listRepositories
   - listBranches
-  - ensureWebhook
-  - cloneCredential
-evm-rpc
-  - request
+  - mintCloneCredential
+  - verifyWebhook
+  - disconnectInstallation
 jetemail
   - send
   - sendBatch
@@ -425,19 +421,27 @@ google-ai-studio
   - translate
 ```
 
-## GitHub App (github-app)
+## GitHub App (github)
 
-Import: @forgezero/providers/git. Each method below is a provider capability that a service attaches by exact version. User OAuth verifies an email and is discarded before the mandatory passkey. App installation credentials are minted on demand, limited to one selected repository, and expire rather than being stored. GitLab or a private forge implements the same Git Connect service without pretending to be GitHub.
+Import: @forgezero/providers/git. Each method below is a provider capability that a service attaches by exact version. The OAuth Server projection verifies an email and revokes the temporary user grant before ForgeZero creates its own session. The Git Connect projection mints repository-scoped installation credentials on demand and never persists them. GitLab or a private forge can implement the same Git Connect service without changing pipelines or Agents.
 
 ```text
 importPath: '@forgezero/providers/git'
-providerId: 'github-app'
+providerId: 'github'
 methods:
-  - listAccounts
+  - beginUserAuthorization
+  - completeUserAuthorization
+  - readVerifiedIdentity
+  - refreshUserGrant
+  - revokeUserGrant
+  - beginInstallation
+  - completeInstallation
+  - listInstallations
   - listRepositories
   - listBranches
-  - ensureWebhook
-  - cloneCredential
+  - mintCloneCredential
+  - verifyWebhook
+  - disconnectInstallation
 credentials:
   - clientSecret
   - privateKey
@@ -448,24 +452,6 @@ config:
   - slug
 ```
 
-## EVM JSON-RPC node (evm-rpc)
-
-Import: @forgezero/providers/chain. Each method below is a provider capability that a service attaches by exact version. Several endpoints per chain is the normal case, not a luxury: public RPC is rate-limited and paid gateways have outages, and a scanner that stops when one is down stops crediting deposits while the money sits on the chain. "Already known" and "nonce too low" are TERMINAL — the transaction is already in flight, so rebroadcasting through another node is how a sweep gets sent twice.
-
-```text
-importPath: '@forgezero/providers/chain'
-providerId: 'evm-rpc'
-methods:
-  - request
-credentials:
-  - url
-  - bearer
-config:
-  - chainId
-  - maxLogRange
-  - timeoutMs
-```
-
 ## JetEmail (jetemail)
 
 Import: @forgezero/providers/email. Each method below is a provider capability that a service attaches by exact version. A 401 is RETRYABLE at the loop level — that key is bad, the next provider's may not be. Treating any 4xx as fatal is what loses the fallback.

package/dist/billing.d.ts

@@ -0,0 +1,305 @@
+/**
+ * Versioned hosted-payment provider boundary.
+ *
+ * ForgeZero never accepts payment credentials. A browser is redirected to (or
+ * embeds) the provider-hosted setup URL and only opaque provider references
+ * return. Concrete HTTP/auth implementations are injected by the API so this
+ * package contains no platform credential source and no vendor secret.
+ */
+import { type FailureKind, type InvokeContext, type ProviderDefinition } from './index';
+export declare const PAYMENT_PROVIDER_KEYS: readonly ["stripe:v1", "paypal:v1", "razorpay:v1"];
+export type PaymentProviderKey = (typeof PAYMENT_PROVIDER_KEYS)[number];
+/**
+ * Persisted operator configuration for the three supported billing providers.
+ * Secrets are deliberately separate write-only fields; the API stores them in
+ * the hidden operational Vault and returns only `hasSecret` to administrators.
+ */
+export declare const paymentProviderDefinitions: readonly [{
+    readonly id: "stripe";
+    readonly label: "Stripe";
+    readonly multiInstance: true;
+    readonly config: {
+        readonly type: "object";
+        readonly properties: {
+            readonly providerApiVersion: {
+                readonly type: "string";
+                readonly minLength: 4;
+                readonly maxLength: 64;
+            };
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["test", "live"];
+            };
+        };
+        readonly required: readonly ["providerApiVersion", "mode"];
+        readonly additionalProperties: false;
+    };
+    readonly credentials: {
+        readonly type: "object";
+        readonly properties: {
+            readonly secretKey: {
+                readonly type: "string";
+                readonly minLength: 16;
+                readonly maxLength: 512;
+                readonly writeOnly: true;
+            };
+            readonly webhookSecret: {
+                readonly type: "string";
+                readonly minLength: 16;
+                readonly maxLength: 512;
+                readonly writeOnly: true;
+            };
+        };
+        readonly required: readonly ["secretKey", "webhookSecret"];
+        readonly additionalProperties: false;
+    };
+    readonly methods: {};
+}, {
+    readonly id: "paypal";
+    readonly label: "PayPal";
+    readonly multiInstance: true;
+    readonly config: {
+        readonly type: "object";
+        readonly properties: {
+            readonly providerApiVersion: {
+                readonly type: "string";
+                readonly minLength: 2;
+                readonly maxLength: 64;
+            };
+            readonly environment: {
+                readonly type: "string";
+                readonly enum: readonly ["sandbox", "live"];
+            };
+        };
+        readonly required: readonly ["providerApiVersion", "environment"];
+        readonly additionalProperties: false;
+    };
+    readonly credentials: {
+        readonly type: "object";
+        readonly properties: {
+            readonly clientId: {
+                readonly type: "string";
+                readonly minLength: 10;
+                readonly maxLength: 512;
+                readonly writeOnly: true;
+            };
+            readonly clientSecret: {
+                readonly type: "string";
+                readonly minLength: 10;
+                readonly maxLength: 512;
+                readonly writeOnly: true;
+            };
+            readonly webhookId: {
+                readonly type: "string";
+                readonly minLength: 4;
+                readonly maxLength: 256;
+                readonly writeOnly: true;
+            };
+        };
+        readonly required: readonly ["clientId", "clientSecret", "webhookId"];
+        readonly additionalProperties: false;
+    };
+    readonly methods: {};
+}, {
+    readonly id: "razorpay";
+    readonly label: "Razorpay";
+    readonly multiInstance: true;
+    readonly config: {
+        readonly type: "object";
+        readonly properties: {
+            readonly providerApiVersion: {
+                readonly type: "string";
+                readonly minLength: 2;
+                readonly maxLength: 64;
+            };
+            readonly mode: {
+                readonly type: "string";
+                readonly enum: readonly ["test", "live"];
+            };
+        };
+        readonly required: readonly ["providerApiVersion", "mode"];
+        readonly additionalProperties: false;
+    };
+    readonly credentials: {
+        readonly type: "object";
+        readonly properties: {
+            readonly keyId: {
+                readonly type: "string";
+                readonly minLength: 8;
+                readonly maxLength: 256;
+                readonly writeOnly: true;
+            };
+            readonly keySecret: {
+                readonly type: "string";
+                readonly minLength: 8;
+                readonly maxLength: 512;
+                readonly writeOnly: true;
+            };
+            readonly webhookSecret: {
+                readonly type: "string";
+                readonly minLength: 8;
+                readonly maxLength: 512;
+                readonly writeOnly: true;
+            };
+        };
+        readonly required: readonly ["keyId", "keySecret", "webhookSecret"];
+        readonly additionalProperties: false;
+    };
+    readonly methods: {};
+}];
+export type PaymentCurrency = 'USD';
+export interface HostedSetupRequest {
+    tenantKey: string;
+    returnUrl: string;
+    cancelUrl: string;
+    idempotencyKey: string;
+    providerCustomerReference?: string;
+}
+export interface HostedSetupResult {
+    hostedUrl: string;
+    setupReference: string;
+    expiresAtTs: number;
+}
+export interface HostedSetupCompletionRequest {
+    tenantKey: string;
+    setupReference: string;
+    idempotencyKey: string;
+}
+/** Only opaque references and safe display metadata cross back into ForgeZero. */
+export interface HostedSetupCompletionResult {
+    providerCustomerReference?: string;
+    providerPaymentMethodReference: string;
+    display: {
+        type: 'card' | 'bank' | 'upi' | 'paypal' | 'other';
+        brand?: string;
+        last4?: string;
+        expiresMonth?: number;
+        expiresYear?: number;
+        label?: string;
+    };
+}
+export interface CustomerRequest {
+    tenantKey: string;
+    email: string;
+    idempotencyKey: string;
+}
+export interface ChargeRequest {
+    tenantKey: string;
+    invoiceKey: string;
+    providerCustomerReference: string;
+    providerPaymentMethodReference: string;
+    amountMinor: string;
+    currency: PaymentCurrency;
+    idempotencyKey: string;
+}
+export interface ChargeResult {
+    providerAttemptReference: string;
+    status: 'succeeded' | 'failed' | 'pending';
+    failureCode?: string;
+}
+export interface VerifiedPaymentWebhook {
+    providerEventId: string;
+    eventType: string;
+    resourceReference: string;
+    /** Normalized terminal meaning; provider-specific event names never leak into settlement logic. */
+    status: 'succeeded' | 'failed' | 'pending';
+    failureCode?: string;
+    occurredAtTs: number;
+}
+export interface ReconciliationResult {
+    providerAttemptReference: string;
+    status: 'succeeded' | 'failed' | 'pending' | 'not_found';
+    failureCode?: string;
+}
+export interface PaymentProviderDriver {
+    createHostedSetup(input: HostedSetupRequest): Promise<HostedSetupResult>;
+    completeHostedSetup(input: HostedSetupCompletionRequest): Promise<HostedSetupCompletionResult>;
+    createCustomer(input: CustomerRequest): Promise<{
+        providerCustomerReference: string;
+    }>;
+    charge(input: ChargeRequest): Promise<ChargeResult>;
+    detachPaymentMethod(input: {
+        tenantKey: string;
+        providerPaymentMethodReference: string;
+        idempotencyKey: string;
+    }): Promise<void>;
+    verifyWebhook(input: {
+        rawBody: Uint8Array;
+        signatureHeaders: Readonly<Record<string, string>>;
+    }): Promise<VerifiedPaymentWebhook>;
+    reconcile(input: {
+        tenantKey: string;
+        providerAttemptReference: string;
+    }): Promise<ReconciliationResult>;
+}
+export declare const billingService: import("./index").ServiceDefinition<"billing", {
+    createHostedSetup: import("./index").ServiceMethodContract<HostedSetupRequest, HostedSetupResult>;
+    completeHostedSetup: import("./index").ServiceMethodContract<HostedSetupCompletionRequest, HostedSetupCompletionResult>;
+    createCustomer: import("./index").ServiceMethodContract<CustomerRequest, {
+        providerCustomerReference: string;
+    }>;
+    charge: import("./index").ServiceMethodContract<ChargeRequest, ChargeResult>;
+    detachPaymentMethod: import("./index").ServiceMethodContract<{
+        tenantKey: string;
+        providerPaymentMethodReference: string;
+        idempotencyKey: string;
+    }, void>;
+    verifyWebhook: import("./index").ServiceMethodContract<{
+        rawBody: Uint8Array;
+        signatureHeaders: Readonly<Record<string, string>>;
+    }, VerifiedPaymentWebhook>;
+    reconcile: import("./index").ServiceMethodContract<{
+        tenantKey: string;
+        providerAttemptReference: string;
+    }, ReconciliationResult>;
+}>;
+export interface VersionedPaymentProvider extends PaymentProviderDriver {
+    readonly key: PaymentProviderKey;
+    readonly provider: 'stripe' | 'paypal' | 'razorpay';
+    readonly contractVersion: 'v1';
+    /** Provider API version selected by operator config and persisted per attempt. */
+    readonly providerApiVersion: string;
+}
+/**
+ * Bind a reviewed provider/version identity to one concrete driver. Legacy API
+ * branches remain separate configured adapters rather than conditionals hidden
+ * inside the current implementation.
+ */
+export declare function paymentProviderAdapter(args: {
+    key: PaymentProviderKey;
+    providerApiVersion: string;
+    driver: PaymentProviderDriver;
+}): VersionedPaymentProvider;
+/**
+ * Build a registry-compatible provider with one explicit current/legacy API
+ * branch. Vendor HTTP code stays outside the service and Vault remains injected.
+ */
+export declare function definePaymentProvider(args: {
+    id: 'stripe' | 'paypal' | 'razorpay';
+    label: string;
+    version: string;
+    driver: {
+        createHostedSetup(context: InvokeContext, input: HostedSetupRequest): Promise<HostedSetupResult>;
+        completeHostedSetup(context: InvokeContext, input: HostedSetupCompletionRequest): Promise<HostedSetupCompletionResult>;
+        createCustomer(context: InvokeContext, input: CustomerRequest): Promise<{
+            providerCustomerReference: string;
+        }>;
+        charge(context: InvokeContext, input: ChargeRequest): Promise<ChargeResult>;
+        detachPaymentMethod(context: InvokeContext, input: {
+            tenantKey: string;
+            providerPaymentMethodReference: string;
+            idempotencyKey: string;
+        }): Promise<void>;
+        verifyWebhook(context: InvokeContext, input: {
+            rawBody: Uint8Array;
+            signatureHeaders: Readonly<Record<string, string>>;
+        }): Promise<VerifiedPaymentWebhook>;
+        reconcile(context: InvokeContext, input: {
+            tenantKey: string;
+            providerAttemptReference: string;
+        }): Promise<ReconciliationResult>;
+    };
+    config: Record<string, unknown>;
+    credentials: Record<string, unknown>;
+    classify?: (error: unknown) => FailureKind;
+}): ProviderDefinition;