@forgezero/providers 0.1.22 → 0.1.24

package/dist/git.d.ts

@@ -0,0 +1,192 @@
+import { type FailureKind, type InvokeContext, type ProviderDefinition } from './index';
+/**
+ * GitHub is one provider authority with two deliberately separate service
+ * bindings. OAuth Server receives only user-authorization methods; Git Connect
+ * receives only installation/repository methods. Both resolve the same
+ * provider instance and therefore the same Vault credential exactly once.
+ */
+export interface GitHubUserAuthorizationRequest {
+    intent: 'signin' | 'signup' | 'invite' | 'recover' | 'session';
+    returnTo: string;
+    state: string;
+    codeChallenge: string;
+}
+export interface GitHubUserAuthorization {
+    url: string;
+    expiresAtTs: number;
+}
+export interface GitHubUserAuthorizationCompletion {
+    code: string;
+    state: string;
+    codeVerifier: string;
+}
+export interface GitHubVerifiedIdentity {
+    providerUserId: string;
+    email: string;
+    displayName?: string;
+}
+export interface GitHubUserGrant {
+    accessToken: string;
+    expiresAtTs?: number;
+    refreshToken?: string;
+    refreshTokenExpiresAtTs?: number;
+}
+export interface GitHubUserGrantRefreshRequest {
+    refreshToken: string;
+}
+export interface GitHubUserGrantRevokeRequest {
+    accessToken: string;
+}
+export interface GitInstallation {
+    id: string;
+    accountId: string;
+    accountLabel: string;
+    accountKind: 'user' | 'organization';
+}
+export interface GitRepository {
+    id: string;
+    fullName: string;
+    private: boolean;
+    defaultBranch: string;
+    cloneUrl: string;
+}
+export interface GitBranch {
+    name: string;
+    protected?: boolean;
+}
+export interface GitCloneCredential {
+    username: string;
+    token: string;
+    expiresAtTs: number;
+}
+export interface GitInstallationStartRequest {
+    returnTo: string;
+    state: string;
+}
+export interface GitInstallationStart {
+    url: string;
+    expiresAtTs: number;
+}
+export interface GitInstallationCompletionRequest {
+    installationId: string;
+    setupAction?: 'install' | 'update';
+    state: string;
+}
+export interface GitInstallationRequest {
+    installationId: string;
+}
+export interface GitRepositoryRequest {
+    installationId: string;
+    cursor?: string;
+}
+export interface GitBranchRequest {
+    installationId: string;
+    repository: string;
+    cursor?: string;
+}
+export interface GitCloneCredentialRequest {
+    installationId: string;
+    repository: string;
+}
+export interface GitWebhookVerificationRequest {
+    rawBody: Uint8Array;
+    signature: string;
+    deliveryId: string;
+    event: string;
+}
+export interface GitWebhookEvent {
+    deliveryId: string;
+    event: string;
+    payload: unknown;
+}
+export declare const githubAppConfigSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly clientId: {
+            readonly type: "string";
+            readonly minLength: 10;
+            readonly maxLength: 128;
+        };
+        readonly appId: {
+            readonly type: "string";
+            readonly pattern: "^[1-9][0-9]{0,19}$";
+        };
+        readonly slug: {
+            readonly type: "string";
+            readonly pattern: "^[a-z0-9][a-z0-9-]{0,99}$";
+        };
+        readonly providerVersion: {
+            readonly type: "string";
+            readonly pattern: "^github-app:[a-z0-9][a-z0-9.-]{0,31}$";
+        };
+        readonly verifiedAtTs: {
+            readonly type: "integer";
+            readonly minimum: 1;
+        };
+    };
+    readonly required: readonly ["clientId", "appId", "slug", "providerVersion", "verifiedAtTs"];
+    readonly additionalProperties: false;
+};
+export declare const githubAppCredentialSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly clientSecret: {
+            readonly type: "string";
+            readonly minLength: 20;
+            readonly maxLength: 512;
+            readonly writeOnly: true;
+        };
+        readonly privateKey: {
+            readonly type: "string";
+            readonly minLength: 800;
+            readonly maxLength: 32768;
+            readonly writeOnly: true;
+        };
+        readonly webhookSecret: {
+            readonly type: "string";
+            readonly minLength: 32;
+            readonly maxLength: 256;
+            readonly writeOnly: true;
+        };
+    };
+    readonly required: readonly ["clientSecret", "privateKey", "webhookSecret"];
+    readonly additionalProperties: false;
+};
+export declare const oauthServerService: import("./index").ServiceDefinition<"oauth-server", {
+    beginUserAuthorization: import("./index").ServiceMethodContract<GitHubUserAuthorizationRequest, GitHubUserAuthorization>;
+    completeUserAuthorization: import("./index").ServiceMethodContract<GitHubUserAuthorizationCompletion, GitHubUserGrant>;
+    readVerifiedIdentity: import("./index").ServiceMethodContract<GitHubUserGrant, GitHubVerifiedIdentity>;
+    refreshUserGrant: import("./index").ServiceMethodContract<GitHubUserGrantRefreshRequest, GitHubUserGrant>;
+    revokeUserGrant: import("./index").ServiceMethodContract<GitHubUserGrantRevokeRequest, void>;
+}>;
+export declare const gitConnectService: import("./index").ServiceDefinition<"git-connect", {
+    beginInstallation: import("./index").ServiceMethodContract<GitInstallationStartRequest, GitInstallationStart>;
+    completeInstallation: import("./index").ServiceMethodContract<GitInstallationCompletionRequest, GitInstallation>;
+    listInstallations: import("./index").ServiceMethodContract<Record<string, never>, readonly GitInstallation[]>;
+    listRepositories: import("./index").ServiceMethodContract<GitRepositoryRequest, readonly GitRepository[]>;
+    listBranches: import("./index").ServiceMethodContract<GitBranchRequest, readonly GitBranch[]>;
+    mintCloneCredential: import("./index").ServiceMethodContract<GitCloneCredentialRequest, GitCloneCredential>;
+    verifyWebhook: import("./index").ServiceMethodContract<GitWebhookVerificationRequest, GitWebhookEvent>;
+    disconnectInstallation: import("./index").ServiceMethodContract<GitInstallationRequest, void>;
+}>;
+export interface GitHubProviderAdapter {
+    beginUserAuthorization(context: InvokeContext, args: GitHubUserAuthorizationRequest): Promise<GitHubUserAuthorization>;
+    completeUserAuthorization(context: InvokeContext, args: GitHubUserAuthorizationCompletion): Promise<GitHubUserGrant>;
+    readVerifiedIdentity(context: InvokeContext, args: GitHubUserGrant): Promise<GitHubVerifiedIdentity>;
+    refreshUserGrant(context: InvokeContext, args: GitHubUserGrantRefreshRequest): Promise<GitHubUserGrant>;
+    revokeUserGrant(context: InvokeContext, args: GitHubUserGrantRevokeRequest): Promise<void>;
+    beginInstallation(context: InvokeContext, args: GitInstallationStartRequest): Promise<GitInstallationStart>;
+    completeInstallation(context: InvokeContext, args: GitInstallationCompletionRequest): Promise<GitInstallation>;
+    listInstallations(context: InvokeContext, args: Record<string, never>): Promise<readonly GitInstallation[]>;
+    listRepositories(context: InvokeContext, args: GitRepositoryRequest): Promise<readonly GitRepository[]>;
+    listBranches(context: InvokeContext, args: GitBranchRequest): Promise<readonly GitBranch[]>;
+    mintCloneCredential(context: InvokeContext, args: GitCloneCredentialRequest): Promise<GitCloneCredential>;
+    verifyWebhook(context: InvokeContext, args: GitWebhookVerificationRequest): Promise<GitWebhookEvent>;
+    disconnectInstallation(context: InvokeContext, args: GitInstallationRequest): Promise<void>;
+}
+/** Define the single GitHub App provider. No OAuth-App compatibility identity exists. */
+export declare function defineGitHubProvider(args: {
+    version: string;
+    adapter: GitHubProviderAdapter;
+    classify?: (error: unknown) => FailureKind;
+}): ProviderDefinition;

package/dist/{chain.js → git.js}

@@ -336,155 +336,87 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.24";
 
-// src/chain.ts
-var hexToNumber = (value) => Number(BigInt(value));
-var TERMINAL_PATTERNS = [
-  "already known",
-  "nonce too low",
-  "already imported",
-  "replacement transaction underpriced",
-  "intrinsic gas too low",
-  "insufficient funds",
-  "exceeds block gas limit",
-  "invalid sender",
-  "execution reverted"
-];
-var evmRpc = defineSingleMethodProvider({
-  id: "evm-rpc",
-  method: "request",
-  label: "EVM JSON-RPC node",
-  multiInstance: true,
-  credentials: {
-    type: "object",
-    properties: {
-      url: { type: "string", writeOnly: true },
-      bearer: { type: "string", writeOnly: true }
-    },
-    required: ["url"],
-    additionalProperties: false
-  },
-  config: {
-    type: "object",
-    properties: {
-      chainId: { type: "integer" },
-      maxLogRange: { type: "integer" },
-      timeoutMs: { type: "integer" }
-    },
-    required: ["chainId"],
-    additionalProperties: false
+// src/git.ts
+var githubAppConfigSchema = {
+  type: "object",
+  properties: {
+    clientId: { type: "string", minLength: 10, maxLength: 128 },
+    appId: { type: "string", pattern: "^[1-9][0-9]{0,19}$" },
+    slug: { type: "string", pattern: "^[a-z0-9][a-z0-9-]{0,99}$" },
+    providerVersion: { type: "string", pattern: "^github-app:[a-z0-9][a-z0-9.-]{0,31}$" },
+    verifiedAtTs: { type: "integer", minimum: 1 }
   },
-  async invoke(context, call) {
-    const config = context.config;
-    const url = await context.secret("url");
-    const bearer = await context.secret("bearer").catch(() => {
-      return;
-    });
-    const rpc = async (method, params) => {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          ...bearer ? { authorization: `Bearer ${bearer}` } : {}
-        },
-        body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
-        signal: context.signal ?? AbortSignal.timeout(config.timeoutMs ?? 15000)
-      });
-      if (!response.ok) {
-        throw new ProviderError("RPC_HTTP", `${method}: HTTP ${response.status}`, {
-          status: response.status
-        });
-      }
-      const body = await response.json();
-      if (body.error) {
-        throw new ProviderError("RPC_ERROR", `${method}: ${body.error.message ?? "error"}`, {
-          code: body.error.code
-        });
-      }
-      if (body.result === undefined) {
-        throw new ProviderError("RPC_EMPTY", `${method}: no result`);
-      }
-      return body.result;
-    };
-    switch (call.op) {
-      case "head":
-        return { op: "head", block: hexToNumber(await rpc("eth_blockNumber", [])) };
-      case "balance":
-        return {
-          op: "balance",
-          wei: BigInt(await rpc("eth_getBalance", [call.address, call.block ?? "latest"]))
-        };
-      case "call":
-        return {
-          op: "call",
-          data: await rpc("eth_call", [
-            { to: call.to, data: call.data },
-            call.block ?? "latest"
-          ])
-        };
-      case "logs": {
-        const span = call.toBlock - call.fromBlock + 1;
-        const cap = config.maxLogRange ?? 2000;
-        if (span > cap) {
-          throw new ProviderError("RPC_RANGE_TOO_WIDE", `Asked for ${span} blocks; this node allows ${cap}. Split the range.`);
-        }
-        const logs = await rpc("eth_getLogs", [
-          {
-            fromBlock: `0x${call.fromBlock.toString(16)}`,
-            toBlock: `0x${call.toBlock.toString(16)}`,
-            ...call.address ? { address: call.address } : {},
-            ...call.topics ? { topics: call.topics } : {}
-          }
-        ]);
-        return {
-          op: "logs",
-          logs: logs.map((log) => ({
-            transactionHash: log.transactionHash,
-            logIndex: hexToNumber(log.logIndex),
-            blockNumber: hexToNumber(log.blockNumber),
-            address: log.address,
-            topics: log.topics,
-            data: log.data
-          }))
-        };
-      }
-      case "nonce":
-        return {
-          op: "nonce",
-          nonce: BigInt(await rpc("eth_getTransactionCount", [call.address, call.block ?? "pending"]))
-        };
-      case "send":
-        return { op: "send", hash: await rpc("eth_sendRawTransaction", [call.raw]) };
-      case "receipt": {
-        const receipt = await rpc("eth_getTransactionReceipt", [call.hash]);
-        if (!receipt)
-          return { op: "receipt", receipt: null };
-        return {
-          op: "receipt",
-          receipt: {
-            hash: call.hash,
-            blockNumber: hexToNumber(receipt.blockNumber ?? "0x0"),
-            success: receipt.status === "0x1"
-          }
-        };
-      }
-    }
+  required: ["clientId", "appId", "slug", "providerVersion", "verifiedAtTs"],
+  additionalProperties: false
+};
+var githubAppCredentialSchema = {
+  type: "object",
+  properties: {
+    clientSecret: { type: "string", minLength: 20, maxLength: 512, writeOnly: true },
+    privateKey: { type: "string", minLength: 800, maxLength: 32768, writeOnly: true },
+    webhookSecret: { type: "string", minLength: 32, maxLength: 256, writeOnly: true }
   },
-  classify(error) {
-    const message = String(error?.message ?? "").toLowerCase();
-    const details = error.details;
-    if (TERMINAL_PATTERNS.some((pattern) => message.includes(pattern)))
-      return "terminal";
-    if (message.includes("split the range"))
-      return "terminal";
-    if (details?.code === -32602)
-      return "terminal";
-    if (details?.status === 429 || message.includes("rate limit") || message.includes("too many"))
-      return "backoff";
-    return "retryable";
+  required: ["clientSecret", "privateKey", "webhookSecret"],
+  additionalProperties: false
+};
+var oauthServerService = defineService({
+  key: "oauth-server",
+  methods: {
+    beginUserAuthorization: serviceMethod(),
+    completeUserAuthorization: serviceMethod(),
+    readVerifiedIdentity: serviceMethod(),
+    refreshUserGrant: serviceMethod(),
+    revokeUserGrant: serviceMethod()
   }
 });
+var gitConnectService = defineService({
+  key: "git-connect",
+  methods: {
+    beginInstallation: serviceMethod(),
+    completeInstallation: serviceMethod(),
+    listInstallations: serviceMethod(),
+    listRepositories: serviceMethod(),
+    listBranches: serviceMethod(),
+    mintCloneCredential: serviceMethod(),
+    verifyWebhook: serviceMethod(),
+    disconnectInstallation: serviceMethod()
+  }
+});
+function defineGitHubProvider(args) {
+  const classify = args.classify ?? (() => "retryable");
+  const branch = (invoke) => defineProviderMethodBranches({
+    currentVersion: args.version,
+    versions: { [args.version]: { version: args.version, lifecycle: "current", invoke, classify } }
+  });
+  return defineProvider({
+    id: "github",
+    label: "GitHub App",
+    multiInstance: false,
+    credentials: githubAppCredentialSchema,
+    config: githubAppConfigSchema,
+    methods: {
+      beginUserAuthorization: branch(args.adapter.beginUserAuthorization),
+      completeUserAuthorization: branch(args.adapter.completeUserAuthorization),
+      readVerifiedIdentity: branch(args.adapter.readVerifiedIdentity),
+      refreshUserGrant: branch(args.adapter.refreshUserGrant),
+      revokeUserGrant: branch(args.adapter.revokeUserGrant),
+      beginInstallation: branch(args.adapter.beginInstallation),
+      completeInstallation: branch(args.adapter.completeInstallation),
+      listInstallations: branch(args.adapter.listInstallations),
+      listRepositories: branch(args.adapter.listRepositories),
+      listBranches: branch(args.adapter.listBranches),
+      mintCloneCredential: branch(args.adapter.mintCloneCredential),
+      verifyWebhook: branch(args.adapter.verifyWebhook),
+      disconnectInstallation: branch(args.adapter.disconnectInstallation)
+    }
+  });
+}
 export {
-  evmRpc
+  oauthServerService,
+  githubAppCredentialSchema,
+  githubAppConfigSchema,
+  gitConnectService,
+  defineGitHubProvider
 };

package/dist/http.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.24";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/index.d.ts

@@ -303,5 +303,5 @@ export interface EmailBatchResult {
     };
     results: readonly EmailBatchItemResult[];
 }
-export declare const VERSION = "0.1.22";
+export declare const VERSION = "0.1.24";
 export {};

package/dist/index.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.24";
 export {
   staticConfig,
   serviceMethod,

package/dist/pool.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.24";
 
 // src/http.ts
 class BudgetExhausted extends ProviderError {

package/dist/storage.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.24";
 
 // src/storage.ts
 var encoder = new TextEncoder;

package/dist/translation.js

@@ -336,7 +336,7 @@ function createService(definition, methods, options = {}) {
     }
   };
 }
-var VERSION = "0.1.22";
+var VERSION = "0.1.24";
 
 // src/translation.ts
 var GOOGLE_ENDPOINT = "https://generativelanguage.googleapis.com/v1beta/models";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/providers",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -15,10 +15,6 @@
       "types": "./dist/email.d.ts",
       "default": "./dist/email.js"
     },
-    "./chain": {
-      "types": "./dist/chain.d.ts",
-      "default": "./dist/chain.js"
-    },
     "./database": {
       "types": "./dist/database.d.ts",
       "default": "./dist/database.js"
@@ -35,10 +31,6 @@
       "types": "./dist/pool.d.ts",
       "default": "./dist/pool.js"
     },
-    "./binance": {
-      "types": "./dist/binance.d.ts",
-      "default": "./dist/binance.js"
-    },
     "./translation": {
       "types": "./dist/translation.d.ts",
       "default": "./dist/translation.js"
@@ -46,6 +38,14 @@
     "./realtime": {
       "types": "./dist/realtime.d.ts",
       "default": "./dist/realtime.js"
+    },
+    "./git": {
+      "types": "./dist/git.d.ts",
+      "default": "./dist/git.js"
+    },
+    "./billing": {
+      "types": "./dist/billing.d.ts",
+      "default": "./dist/billing.js"
     }
   },
   "scripts": {
@@ -85,6 +85,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgezero/runtime": "^0.1.14"
+    "@forgezero/runtime": "^0.1.15"
   }
 }

package/dist/binance.d.ts

@@ -1,27 +0,0 @@
-import { VenueError, type VenueAdapter, type MarketType, type OrderStatus } from '@forgezero/runtime/finance/venues';
-export interface BinanceCredentials {
-    apiKey: string;
-    apiSecret: string;
-}
-export interface BinanceOptions {
-    credentials: BinanceCredentials;
-    /** Override for testnet, or for a test. */
-    hosts?: Partial<Record<MarketType, string>>;
-    fetch?: typeof globalThis.fetch;
-    /**
-     * How far a request may be delayed before Binance refuses it.
-     *
-     * 5s rather than the 60s maximum. A signed order that arrives a minute late
-     * is an order placed into a market that has moved, and accepting it is worse
-     * than being told to retry.
-     */
-    recvWindowMs?: number;
-    now?: () => number;
-}
-/** Binance spells `BTC/USDT` as `BTCUSDT`. Denormalised here and nowhere else. */
-export declare const binanceSymbol: (symbol: string) => string;
-/** Binance statuses → ours. An unknown one is `rejected`, never silently `accepted`. */
-export declare function toOrderStatus(status: string): OrderStatus;
-export declare function createBinanceAdapter(options: BinanceOptions): VenueAdapter;
-/** Turn a Binance error into something that names the actual cause. */
-export declare function readBinanceError(error: unknown): VenueError | undefined;

package/dist/chain.d.ts

@@ -1,99 +0,0 @@
-/**
- * A blockchain node, behind the same failover every other service gets.
- *
- * Reading a chain is a PROVIDER problem, not a runtime one, and the distinction
- * is not bookkeeping. A node needs a credential, it rate-limits, it goes down,
- * and the answer when it does is to ask a different one — which is precisely
- * what the registry already does for email and storage. Deriving an address
- * needs none of that and lives in `runtime/finance/custody`.
- *
- * ## Why several nodes is the normal case, not a luxury
- *
- * Public RPC endpoints are rate-limited and unreliable, and paid ones have
- * outages like anything else. A deposit scanner that stops when one endpoint is
- * down stops CREDITING DEPOSITS, and the user's money is on the chain the whole
- * time. Priority and health belong here so a scanner never has to know which
- * node answered.
- *
- * ## The classification is the load-bearing part
- *
- *   terminal   our request is malformed, or the chain rejected the transaction
- *              on its merits. Every node will say the same thing, and asking
- *              three of them buries the real reason under two duplicates.
- *   backoff    rate limited. The node is healthy and we are asking too fast;
- *              striking it would punish the one that is working.
- *   retryable  this node is behind, broken, or its key is bad. The next may
- *              be fine.
- *
- * "Already known" and "nonce too low" are the interesting cases. Both mean the
- * transaction is ALREADY IN FLIGHT, so they are terminal rather than retryable:
- * rebroadcasting through another node cannot help, and treating them as failure
- * is how a sweep gets sent twice.
- */
-export type ChainCall = {
-    op: 'head';
-} | {
-    op: 'balance';
-    address: string;
-    block?: string;
-} | {
-    op: 'call';
-    to: string;
-    data: string;
-    block?: string;
-} | {
-    op: 'logs';
-    fromBlock: number;
-    toBlock: number;
-    address?: string;
-    topics?: (string | string[] | null)[];
-} | {
-    op: 'nonce';
-    address: string;
-    block?: 'pending' | 'latest';
-} | {
-    op: 'send';
-    raw: string;
-} | {
-    op: 'receipt';
-    hash: string;
-};
-export interface ChainLog {
-    transactionHash: string;
-    logIndex: number;
-    blockNumber: number;
-    address: string;
-    topics: string[];
-    data: string;
-}
-export interface ChainReceipt {
-    hash: string;
-    blockNumber: number;
-    /** True only when the chain executed it successfully. */
-    success: boolean;
-}
-export type ChainResult = {
-    op: 'head';
-    block: number;
-} | {
-    op: 'balance';
-    wei: bigint;
-} | {
-    op: 'call';
-    data: string;
-} | {
-    op: 'logs';
-    logs: ChainLog[];
-} | {
-    op: 'nonce';
-    nonce: bigint;
-} | {
-    op: 'send';
-    hash: string;
-}
-/** `null` when the transaction has not mined yet — not an error. */
- | {
-    op: 'receipt';
-    receipt: ChainReceipt | null;
-};
-export declare const evmRpc: import("./index").ProviderDefinition<Record<"request", import("./index").ProviderMethodSpec<ChainCall, ChainResult>>>;