@paybond/kit 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,6 @@
 # `@paybond/kit`
 
-Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, and tenant-scoped ledger provenance reads.
-
-It does **not** currently expose a first-class Signal client or Signal analytics/reputation API surface. Signal remains a separate platform surface today.
+Paybond Kit for TypeScript provides a tenant-bound Harbor client, gateway-backed service-account sessions, capability verification, canonical signing helpers for intent creation and evidence submission, tenant-scoped ledger provenance reads, and tenant-scoped Signal analytics and reputation reads.
 
 Install the public package with:
 
@@ -22,7 +20,7 @@ npm install @paybond/kit
 
 ## Tenant isolation
 
-Every session is bound to the tenant realm echoed by the gateway `POST /v1/auth/harbor-access` exchange.
+Every session is bound to the tenant realm echoed by gateway-authenticated service-account introspection and Harbor access exchange flows.
 
 - Do not pass tenant ids by hand for normal SDK usage.
 - Construct one `Paybond` session per tenant/service account.
@@ -59,6 +57,8 @@ try {
 
 - `Paybond.open(...)` for gateway-authenticated, tenant-derived Harbor sessions
 - `HarborClient` for capability verification, intent creation, evidence submission, and ledger reads
+- `GatewaySignalClient` and `ServiceAccountSignalSession` for tenant-scoped Signal reads
+- `paybond.signal` on `Paybond` sessions opened from one service-account API key
 - `PaybondIntents` helpers for principal-signed intent creation and payee-signed evidence submission
 - Low-level signing helpers exported for advanced callers
 
@@ -66,8 +66,6 @@ try {
 
 ## What it does not include
 
-- No first-class `SignalClient`
-- No Signal reputation or analytics fetch API
 - No operator-tier settlement or console workflows
 
 ## Docs

package/dist/index.d.ts

@@ -44,6 +44,19 @@ export declare class GatewayAuthError extends Error {
         bodyText?: string;
     });
 }
+/**
+ * Structured HTTP failure from gateway Signal read routes.
+ */
+export declare class SignalHttpError extends Error {
+    readonly statusCode: number;
+    readonly url: string;
+    readonly bodyText: string;
+    constructor(message: string, init: {
+        statusCode: number;
+        url: string;
+        bodyText: string;
+    });
+}
 /**
  * Exchanges a `paybond_sk_` API key for short-lived Harbor JWTs and caches tenant realm from the
  * gateway response (no separate tenant env var for the default path).
@@ -191,6 +204,42 @@ export declare class HarborClient {
      */
     getLedgerMerkleLatest(): Promise<Record<string, unknown>>;
 }
+type GatewaySignalClientOptions = {
+    staticGatewayBearerToken: string;
+    maxRetries?: number;
+};
+/**
+ * Tenant-bound reader for gateway Signal routes.
+ */
+export declare class GatewaySignalClient {
+    private readonly base;
+    readonly tenantId: string;
+    private readonly bearerToken;
+    private readonly maxRetries;
+    constructor(gatewayBaseUrl: string, tenantId: string, options: GatewaySignalClientOptions);
+    private fetchGetWithRetries;
+    private assertTenant;
+    private scoreQuery;
+    getReputationReceipt(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
+    getPortfolioSummary(scoreVersion?: string): Promise<Record<string, unknown>>;
+    getOperatorExplanation(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
+    getOperatorReviewStatus(operatorDid: string, scoreVersion?: string): Promise<Record<string, unknown> | null>;
+}
+export type ServiceAccountSignalSessionInit = {
+    gatewayBaseUrl: string;
+    apiKey: string;
+    principalPath?: string;
+    maxRetries?: number;
+};
+/**
+ * Read-only tenant-bound Signal session for one service-account API key.
+ */
+export declare class ServiceAccountSignalSession {
+    readonly signal: GatewaySignalClient;
+    private constructor();
+    static open(init: ServiceAccountSignalSessionInit): Promise<ServiceAccountSignalSession>;
+    aclose(): Promise<void>;
+}
 /** Parameters for {@link PaybondIntents.create} (tenant is taken from the bound Harbor client). */
 export type PaybondCreateIntentParams = Omit<BuildSignedCreateIntentParams, "tenantId" | "intentId"> & {
     intentId?: string;
@@ -221,6 +270,7 @@ export declare class PaybondIntents {
  */
 export declare class Paybond {
     readonly harbor: HarborClient;
+    readonly signal: GatewaySignalClient;
     readonly intents: PaybondIntents;
     private readonly session;
     private constructor();

package/dist/index.js

@@ -32,6 +32,21 @@ export class GatewayAuthError extends Error {
         this.bodyText = init?.bodyText;
     }
 }
+/**
+ * Structured HTTP failure from gateway Signal read routes.
+ */
+export class SignalHttpError extends Error {
+    statusCode;
+    url;
+    bodyText;
+    constructor(message, init) {
+        super(message);
+        this.name = "SignalHttpError";
+        this.statusCode = init.statusCode;
+        this.url = init.url;
+        this.bodyText = init.bodyText;
+    }
+}
 function normalizeBase(url) {
     return url.trim().replace(/\/+$/, "");
 }
@@ -507,6 +522,226 @@ export class HarborClient {
         return body;
     }
 }
+const DEFAULT_PRINCIPAL_PATH = "/v1/auth/principal";
+function assertJSONObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("expected JSON object");
+    }
+    return value;
+}
+/**
+ * Tenant-bound reader for gateway Signal routes.
+ */
+export class GatewaySignalClient {
+    base;
+    tenantId;
+    bearerToken;
+    maxRetries;
+    constructor(gatewayBaseUrl, tenantId, options) {
+        this.base = normalizeBase(gatewayBaseUrl) + "/";
+        this.tenantId = tenantId.trim();
+        this.bearerToken = options.staticGatewayBearerToken.trim();
+        this.maxRetries = Math.max(1, options.maxRetries ?? 3);
+    }
+    async fetchGetWithRetries(url) {
+        let lastErr;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            let res;
+            try {
+                res = await fetch(url, {
+                    method: "GET",
+                    headers: {
+                        accept: "application/json",
+                        authorization: `Bearer ${this.bearerToken}`,
+                    },
+                });
+            }
+            catch (e) {
+                lastErr = e;
+                if (attempt + 1 >= this.maxRetries)
+                    throw e;
+                await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+                continue;
+            }
+            if ([429, 500, 502, 503, 504].includes(res.status)) {
+                if (attempt + 1 >= this.maxRetries) {
+                    return res;
+                }
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            return res;
+        }
+        throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+    }
+    assertTenant(body, url) {
+        const tid = String(body.tenant_id ?? "");
+        if (tid !== this.tenantId) {
+            throw new Error(`signal tenant mismatch: client=${this.tenantId} gateway=${tid} url=${url}`);
+        }
+    }
+    scoreQuery(scoreVersion) {
+        if (!scoreVersion || !scoreVersion.trim()) {
+            return "";
+        }
+        return `?score_version=${encodeURIComponent(scoreVersion.trim())}`;
+    }
+    async getReputationReceipt(operatorDid, scoreVersion) {
+        const enc = encodeURIComponent(operatorDid);
+        const url = `${this.base}reputation/${enc}${this.scoreQuery(scoreVersion)}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (res.status === 404) {
+            return null;
+        }
+        if (!res.ok) {
+            throw new SignalHttpError(`Signal receipt HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        const receipt = assertJSONObject(body.receipt);
+        const tenant = String(receipt.tenant_id ?? "");
+        const echoedOperator = String(receipt.operator_did ?? "");
+        if (tenant !== this.tenantId) {
+            throw new Error(`signal receipt tenant mismatch: client=${this.tenantId} gateway=${tenant}`);
+        }
+        if (echoedOperator !== operatorDid) {
+            throw new Error(`signal receipt operator mismatch: requested=${operatorDid} gateway=${echoedOperator}`);
+        }
+        return body;
+    }
+    async getPortfolioSummary(scoreVersion) {
+        const url = `${this.base}signal/v1/portfolio/summary${this.scoreQuery(scoreVersion)}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new SignalHttpError(`Signal portfolio summary HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        return body;
+    }
+    async getOperatorExplanation(operatorDid, scoreVersion) {
+        const enc = encodeURIComponent(operatorDid);
+        const url = `${this.base}signal/v1/operators/${enc}/explanation${this.scoreQuery(scoreVersion)}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (res.status === 404) {
+            return null;
+        }
+        if (!res.ok) {
+            throw new SignalHttpError(`Signal explanation HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        if (String(body.operator_did ?? "") !== operatorDid) {
+            throw new Error(`signal explanation operator mismatch: requested=${operatorDid} gateway=${String(body.operator_did ?? "")}`);
+        }
+        return body;
+    }
+    async getOperatorReviewStatus(operatorDid, scoreVersion) {
+        const enc = encodeURIComponent(operatorDid);
+        const url = `${this.base}signal/v1/operators/${enc}/review-status${this.scoreQuery(scoreVersion)}`;
+        const res = await this.fetchGetWithRetries(url);
+        const text = await res.text();
+        if (res.status === 404) {
+            return null;
+        }
+        if (!res.ok) {
+            throw new SignalHttpError(`Signal review status HTTP ${res.status}: ${text}`, {
+                statusCode: res.status,
+                url,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        this.assertTenant(body, url);
+        if (String(body.operator_did ?? "") !== operatorDid) {
+            throw new Error(`signal review operator mismatch: requested=${operatorDid} gateway=${String(body.operator_did ?? "")}`);
+        }
+        return body;
+    }
+}
+async function resolveGatewayTenantId(gatewayBaseUrl, apiKey, principalPath, maxRetries) {
+    const base = normalizeBase(gatewayBaseUrl);
+    const path = principalPath.startsWith("/") ? principalPath : `/${principalPath}`;
+    const url = `${base}${path}`;
+    let lastErr;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        let res;
+        try {
+            res = await fetch(url, {
+                method: "GET",
+                headers: {
+                    accept: "application/json",
+                    authorization: `Bearer ${apiKey.trim()}`,
+                },
+            });
+        }
+        catch (e) {
+            lastErr = e;
+            if (attempt + 1 >= maxRetries) {
+                throw e;
+            }
+            await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+            continue;
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            if ([429, 500, 502, 503, 504].includes(res.status) && attempt + 1 < maxRetries) {
+                const raSec = parseRetryAfterSeconds(res.headers.get("retry-after"));
+                const delayMs = raSec != null ? raSec * 1000 : backoffMs(attempt);
+                await new Promise((r) => setTimeout(r, delayMs));
+                continue;
+            }
+            throw new GatewayAuthError(`gateway principal HTTP ${res.status}`, {
+                statusCode: res.status,
+                bodyText: text,
+            });
+        }
+        const body = assertJSONObject(JSON.parse(text));
+        const tenant = String(body.tenant_id ?? "").trim();
+        if (!tenant) {
+            throw new GatewayAuthError("gateway principal JSON missing tenant_id", {
+                bodyText: text,
+            });
+        }
+        return tenant;
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+/**
+ * Read-only tenant-bound Signal session for one service-account API key.
+ */
+export class ServiceAccountSignalSession {
+    signal;
+    constructor(signal) {
+        this.signal = signal;
+    }
+    static async open(init) {
+        const tenantId = await resolveGatewayTenantId(init.gatewayBaseUrl, init.apiKey, init.principalPath ?? DEFAULT_PRINCIPAL_PATH, Math.max(1, init.maxRetries ?? 3));
+        return new ServiceAccountSignalSession(new GatewaySignalClient(init.gatewayBaseUrl, tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        }));
+    }
+    async aclose() {
+        await Promise.resolve();
+    }
+}
 /**
  * Ergonomic intent helpers: principal-signed intent create and payee-signed evidence.
  */
@@ -545,17 +780,23 @@ export class PaybondIntents {
  */
 export class Paybond {
     harbor;
+    signal;
     intents;
     session;
-    constructor(session) {
+    constructor(session, signal) {
         this.session = session;
         this.harbor = session.harbor;
+        this.signal = signal;
         this.intents = new PaybondIntents(session.harbor);
     }
     /** Open a tenant-bound session via gateway `harbor-access` exchange. */
     static async open(init) {
         const session = await ServiceAccountHarborSession.open(init);
-        return new Paybond(session);
+        const signal = new GatewaySignalClient(init.gatewayBaseUrl, session.harbor.tenantId, {
+            staticGatewayBearerToken: init.apiKey,
+            maxRetries: init.maxRetries ?? 3,
+        });
+        return new Paybond(session, signal);
     }
     async rotateHarborToken() {
         await this.session.rotateHarborToken();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paybond/kit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Paybond Kit for TypeScript: tenant-bound Harbor sessions, capability verification, and signed intent/evidence flows.",
   "license": "Apache-2.0",
   "type": "module",
@@ -22,7 +22,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/nonameuserd/paybond-kit.git"
+    "url": "git+https://github.com/nonameuserd/paybond-kit.git"
   },
   "homepage": "https://github.com/nonameuserd/paybond-kit",
   "bugs": {