@forgezero/providers 0.1.22 → 0.1.24

package/README.md

@@ -40,11 +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
 
@@ -258,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
 
@@ -373,13 +327,85 @@ import {
 export const selectedCapability = RealtimeProviderError;
 ```
 
+<a id="forgezero-providers-git"></a>
+## @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. 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 {
+  defineGitHubProvider,
+} from '@forgezero/providers/git';
+```
+
+## @forgezero/providers/git — 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 {
+  defineGitHubProvider,
+} from '@forgezero/providers/git';
+
+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
 
 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
-evm-rpc
-  - request
+github
+  - beginUserAuthorization
+  - completeUserAuthorization
+  - readVerifiedIdentity
+  - refreshUserGrant
+  - revokeUserGrant
+  - beginInstallation
+  - completeInstallation
+  - listInstallations
+  - listRepositories
+  - listBranches
+  - mintCloneCredential
+  - verifyWebhook
+  - disconnectInstallation
 jetemail
   - send
   - sendBatch
@@ -395,22 +421,35 @@ google-ai-studio
   - translate
 ```
 
-## EVM JSON-RPC node (evm-rpc)
+## GitHub App (github)
 
-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.
+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/chain'
-providerId: 'evm-rpc'
+importPath: '@forgezero/providers/git'
+providerId: 'github'
 methods:
-  - request
+  - beginUserAuthorization
+  - completeUserAuthorization
+  - readVerifiedIdentity
+  - refreshUserGrant
+  - revokeUserGrant
+  - beginInstallation
+  - completeInstallation
+  - listInstallations
+  - listRepositories
+  - listBranches
+  - mintCloneCredential
+  - verifyWebhook
+  - disconnectInstallation
 credentials:
-  - url
-  - bearer
+  - clientSecret
+  - privateKey
+  - webhookSecret
 config:
-  - chainId
-  - maxLogRange
-  - timeoutMs
+  - clientId
+  - appId
+  - slug
 ```
 
 ## JetEmail (jetemail)

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;