stellarium-ts 0.17.0 → 0.18.0

package/dist/client/operatorClient.d.ts

@@ -9,6 +9,7 @@ export interface FixedPaymentVoucher {
     expiresAt: string;
     invocationHash: string;
     publicKey: string;
+    runId?: string;
 }
 export interface InferenceVoucher {
     kind: 'inference';
@@ -23,6 +24,7 @@ export interface InferenceVoucher {
     expiresAt: string;
     invocationHash: string;
     publicKey: string;
+    runId?: string;
 }
 export interface FixedPaymentSubmission {
     voucher: FixedPaymentVoucher;
@@ -43,6 +45,23 @@ export type AuthorizeResult = {
     status: number;
     error: string;
 };
+/** What a node sends to authorize a script run billed to an API client. Matches apps/operator/src/runs/runService.ts. */
+export interface RunAuthorizationRequest {
+    /** The run token the caller presented. */
+    token: string;
+    runId: string;
+    source: string;
+}
+/** The operator's hold for a run: up to `heldMicroUsd` for the script's tokens and its paid calls together. */
+export type RunAuthorizeResult = {
+    ok: true;
+    heldMicroUsd: number;
+    maxTokens: number;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
 export declare const OPERATOR_MAX_RETRIES = 5;
 /** Authorization runs while the caller waits, so it gives up much sooner than capture and release. */
 export declare const AUTHORIZE_MAX_RETRIES = 2;
@@ -67,7 +86,7 @@ export declare class OperatorClient {
      * enrolls the node first; a node that is already enrolled ignores the token. Throws if the node is
      * not enrolled or the operator refuses.
      */
-    session(enrollmentToken?: string): Promise<{
+    session(enrollmentToken?: string, baseUrl?: string): Promise<{
         organizationId: string;
     }>;
     /**
@@ -75,6 +94,22 @@ export declare class OperatorClient {
      * running the paid function. An unreachable operator is reported as a 503 refusal.
      */
     authorize(voucher: FixedPaymentVoucher | InferenceVoucher): Promise<AuthorizeResult>;
+    /**
+     * Asks the operator to hold a script run's cost on the paying API client's organization, before running
+     * it. An unreachable operator is reported as a 503 refusal.
+     */
+    authorizeRun(request: RunAuthorizationRequest): Promise<RunAuthorizeResult>;
+    /** Charges a held run for the tokens its script executed, and releases the rest of its hold. */
+    captureRun(request: {
+        runId: string;
+        tokens: number;
+    }): Promise<void>;
+    /** Releases a held run without charging it, for a script this node failed to run. */
+    releaseRun(request: {
+        runId: string;
+    }): Promise<void>;
+    /** Authorization runs while the caller waits, so it retries briefly and reports an unreachable operator as 503. */
+    private hold;
     /** Charges a held voucher: its amount, or for inference the reported usage capped at the hold. */
     capture(payment: PaymentSubmission): Promise<void>;
     /** Releases a held voucher without charging it, for a call that failed or cost nothing. */

package/dist/client/operatorClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operatorClient.d.ts","sourceRoot":"","sources":["../../src/client/operatorClient.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG,0BAA0B,CAAC;AAEpF,MAAM,WAAW,mBAAmB;IAChC,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC,EAAE,MAAM,CAAC;IAC1C,kCAAkC,EAAE,MAAM,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,mBAAmB,CAAC;CAChC;AAED,yHAAyH;AACzH,MAAM,WAAW,0BAA0B;IACvC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,KAAK,EAAE;QACH,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACxB,CAAC;CACL;AAED,2GAA2G;AAC3G,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F,eAAO,MAAM,oBAAoB,IAAI,CAAC;AACtC,sGAAsG;AACtG,eAAO,MAAM,qBAAqB,IAAI,CAAC;AACvC,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAwB1C,uFAAuF;AACvF,qBAAa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,GAAG;IAAsB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAAU,OAAO,CAAC,QAAQ,CAAC,UAAU;IAArH,YAA6B,GAAG,EAAE,MAAM,GAAG,SAAS,EAAmB,SAAS,EAAE,MAAM,EAAmB,UAAU,EAAE,MAAM,EAAI;IAEjI;;;;OAIG;YACW,IAAI;IA+BlB;;;;OAIG;IACG,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAM3E;IAED;;;OAGG;IACG,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAczF;IAED,kGAAkG;IAC5F,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEvD;IAED,2FAA2F;IACrF,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E;IAED,6HAA6H;YAC/G,MAAM;CAMvB"}
+{"version":3,"file":"operatorClient.d.ts","sourceRoot":"","sources":["../../src/client/operatorClient.ts"],"names":[],"mappings":"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"}

package/dist/client/operatorClient.js

@@ -76,8 +76,9 @@ export class OperatorClient {
      * enrolls the node first; a node that is already enrolled ignores the token. Throws if the node is
      * not enrolled or the operator refuses.
      */
-    async session(enrollmentToken) {
-        const response = await this.post('/nodes/session', enrollmentToken ? { enrollmentToken } : {}, OPERATOR_MAX_RETRIES, OPERATOR_BASE_DELAY_MS);
+    async session(enrollmentToken, baseUrl) {
+        const body = { ...(enrollmentToken ? { enrollmentToken } : {}), ...(baseUrl ? { baseUrl } : {}) };
+        const response = await this.post('/nodes/session', body, OPERATOR_MAX_RETRIES, OPERATOR_BASE_DELAY_MS);
         if (!response.ok) {
             throw new Error(`Operator refused this node's session: ${await errorMessage(response)}`);
         }
@@ -88,16 +89,40 @@ export class OperatorClient {
      * running the paid function. An unreachable operator is reported as a 503 refusal.
      */
     async authorize(voucher) {
+        const result = await this.hold('/payments/authorize', { voucher });
+        return result.ok ? { ok: true } : result;
+    }
+    /**
+     * Asks the operator to hold a script run's cost on the paying API client's organization, before running
+     * it. An unreachable operator is reported as a 503 refusal.
+     */
+    async authorizeRun(request) {
+        const result = await this.hold('/runs/authorize', request);
+        if (!result.ok)
+            return result;
+        const { heldMicroUsd, maxTokens } = result.body;
+        return { ok: true, heldMicroUsd, maxTokens };
+    }
+    /** Charges a held run for the tokens its script executed, and releases the rest of its hold. */
+    async captureRun(request) {
+        await this.settle('/runs/capture', request);
+    }
+    /** Releases a held run without charging it, for a script this node failed to run. */
+    async releaseRun(request) {
+        await this.settle('/runs/release', request);
+    }
+    /** Authorization runs while the caller waits, so it retries briefly and reports an unreachable operator as 503. */
+    async hold(path, body) {
         let response;
         try {
-            response = await this.post('/payments/authorize', { voucher }, AUTHORIZE_MAX_RETRIES, AUTHORIZE_BASE_DELAY_MS);
+            response = await this.post(path, body, AUTHORIZE_MAX_RETRIES, AUTHORIZE_BASE_DELAY_MS);
         }
         catch (error) {
-            console.error('Failed to reach the operator to authorize a payment', error);
+            console.error(`Failed to reach the operator for ${path}`, error);
             return { ok: false, status: 503, error: 'Payment operator is unavailable' };
         }
         if (response.ok) {
-            return { ok: true };
+            return { ok: true, body: await response.json().catch(() => undefined) };
         }
         // Retries ran out on a transient failure: the caller may try again later.
         const status = RETRYABLE_STATUSES.has(response.status) ? 503 : response.status;

package/dist/client/runTokens.d.ts

@@ -0,0 +1,23 @@
+import { type JWTVerifyGetKey } from "jose";
+/** The `iss` of every run token. Copied from RUN_TOKEN_ISSUER in apps/operator/src/runs/tokens.ts. */
+export declare const RUN_TOKEN_ISSUER = "stellarium";
+/** Who a run token lets run scripts on this node, and which organization pays. */
+export interface RunTokenClaims {
+    clientId: string;
+    organizationId: string;
+}
+/** Whether `token` has the three base64url segments of a JWT, as opposed to an API key. */
+export declare function looksLikeJwt(token: string): boolean;
+/**
+ * Verifies the run tokens API clients get from the operator's `POST /v1/oauth/token`, against the
+ * operator's published keys. A token is only valid at the node whose public key is its audience.
+ */
+export declare class RunTokenVerifier {
+    private readonly nodePublicKey;
+    private readonly keys;
+    /** `keys` replaces fetching `{operatorUrl}/.well-known/jwks.json`, in tests. */
+    constructor(operatorUrl: string, nodePublicKey: string, keys?: JWTVerifyGetKey);
+    /** The token's claims, or undefined unless it is signed by the operator, unexpired and addressed to this node. */
+    verify(token: string): Promise<RunTokenClaims | undefined>;
+}
+//# sourceMappingURL=runTokens.d.ts.map

package/dist/client/runTokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runTokens.d.ts","sourceRoot":"","sources":["../../src/client/runTokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,eAAe,EAAa,MAAM,MAAM,CAAC;AAE3E,sGAAsG;AACtG,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,2FAA2F;AAC3F,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AACH,qBAAa,gBAAgB;IAIQ,OAAO,CAAC,QAAQ,CAAC,aAAa;IAH/D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAkB;IAEvC,gFAAgF;IAChF,YAAY,WAAW,EAAE,MAAM,EAAmB,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,eAAe,EAG9F;IAED,kHAAkH;IAC5G,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAU/D;CACJ"}

package/dist/client/runTokens.js

@@ -0,0 +1,34 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+/** The `iss` of every run token. Copied from RUN_TOKEN_ISSUER in apps/operator/src/runs/tokens.ts. */
+export const RUN_TOKEN_ISSUER = 'stellarium';
+/** Whether `token` has the three base64url segments of a JWT, as opposed to an API key. */
+export function looksLikeJwt(token) {
+    return /^[\w-]+\.[\w-]+\.[\w-]+$/.test(token);
+}
+/**
+ * Verifies the run tokens API clients get from the operator's `POST /v1/oauth/token`, against the
+ * operator's published keys. A token is only valid at the node whose public key is its audience.
+ */
+export class RunTokenVerifier {
+    nodePublicKey;
+    keys;
+    /** `keys` replaces fetching `{operatorUrl}/.well-known/jwks.json`, in tests. */
+    constructor(operatorUrl, nodePublicKey, keys) {
+        this.nodePublicKey = nodePublicKey;
+        // Cached, and refetched when a token names a key it doesn't have.
+        this.keys = keys ?? createRemoteJWKSet(new URL(`${operatorUrl}/.well-known/jwks.json`));
+    }
+    /** The token's claims, or undefined unless it is signed by the operator, unexpired and addressed to this node. */
+    async verify(token) {
+        try {
+            const { payload } = await jwtVerify(token, this.keys, { issuer: RUN_TOKEN_ISSUER, audience: this.nodePublicKey, algorithms: ['EdDSA'] });
+            if (typeof payload.sub !== 'string' || typeof payload.org !== 'string') {
+                return undefined;
+            }
+            return { clientId: payload.sub, organizationId: payload.org };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { StellariumNode, resolveConfig, type StellariumNodeOptions } from './server.js';
 export type { NodeConfig } from './service.js';
 export type { StellariumFixedPaymentManifest, StellariumInferencePaymentManifest, StellariumResource, StellariumResourceFunction, StellariumResourceFunctionKind, StellariumResourceFunctionParameter, StellariumResourceFunctionPaymentManifest, } from './resource/repository.js';
-export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, type InferenceEstimate, type InferencePaymentVoucher, type PaymentVoucher, } from './resource/invoker.js';
+export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, type RunContext, type InferenceEstimate, type InferencePaymentVoucher, type PaymentVoucher, } from './resource/invoker.js';
 export { inferenceCharge, MAX_TOKENS_PARAMETER, type InferenceResult, type InferenceUsage } from './resource/inference.js';
-export type { FixedPaymentVoucher, InferencePaymentSubmission, InferenceVoucher, PaymentSubmission } from './client/operatorClient.js';
+export type { FixedPaymentVoucher, InferencePaymentSubmission, InferenceVoucher, PaymentSubmission, RunAuthorizationRequest } from './client/operatorClient.js';
+export { RUN_TOKEN_ISSUER, RunTokenVerifier, type RunTokenClaims } from './client/runTokens.js';
 export { OPERATOR_AUTH_SCHEME, operatorAuthorization, operatorRequestPayload } from './client/operatorAuth.js';
 export { grantHash, grantPayload, grantRenewalPayload, grantRequestPayload, grantsHash, CLOCK_SKEW_TOLERANCE_MS, invocationAuthorizationPayload, MAX_AUTHORIZATION_LIFETIME_MS, MAX_GRANT_CHAIN_LENGTH, MAX_GRANT_LIFETIME_MS, type Capability, type Grant, type GrantRenewalRequest, type GrantRequest, type InvocationAuthorization, } from './grant/grant.js';
 export type { ApproveGrant, GrantApproval, GrantOptions } from './grant/service.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EACR,8BAA8B,EAC9B,kCAAkC,EAClC,kBAAkB,EAClB,0BAA0B,EAC1B,8BAA8B,EAC9B,mCAAmC,EACnC,yCAAyC,GAC5C,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACH,0BAA0B,EAC1B,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC3H,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEvI,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAE/G,OAAO,EACH,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACvB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,uBAAuB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EACR,8BAA8B,EAC9B,kCAAkC,EAClC,kBAAkB,EAClB,0BAA0B,EAC1B,8BAA8B,EAC9B,mCAAmC,EACnC,yCAAyC,GAC5C,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACH,0BAA0B,EAC1B,uBAAuB,EACvB,cAAc,EACd,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,cAAc,GACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC3H,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAEhK,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEhG,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAE/G,OAAO,EACH,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACvB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,KAAK,EACV,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,uBAAuB,GAC/B,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACpF,YAAY,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -2,6 +2,8 @@ export { StellariumNode, resolveConfig } from './server.js';
 // The voucher wire format, so the operator and other settlers can test against the real signer.
 export { CombinationResourceInvoker, inferenceVoucherPayload, invocationHash, paymentVoucherPayload, } from './resource/invoker.js';
 export { inferenceCharge, MAX_TOKENS_PARAMETER } from './resource/inference.js';
+// Run token verification, so the operator can test its tokens against the real verifier.
+export { RUN_TOKEN_ISSUER, RunTokenVerifier } from './client/runTokens.js';
 // The operator request signature, so the operator can test against the real signer.
 export { OPERATOR_AUTH_SCHEME, operatorAuthorization, operatorRequestPayload } from './client/operatorAuth.js';
 // Grant wire format, so other implementations can test against the real signer.

package/dist/resource/inference.d.ts

@@ -27,6 +27,8 @@ export declare function isInferenceFunction(fn: Pick<StellariumResourceFunction,
 export declare function inferenceCharge(rates: InferenceRates, inputTokens: number, outputTokens: number): number;
 /** The call's `maxTokens` value, or undefined unless it is a positive int32. */
 export declare function parseMaxTokens(parameters: ResourceFunctionCallParameter[]): number | undefined;
+/** The function's own input-token estimate, or undefined if its estimator failed or returned something other than a count. */
+export declare function estimateInputTokens(fn: StellariumResourceFunction, parameters: ResourceFunctionCallParameter[]): Promise<number | undefined>;
 /** The usage an inference `exec` reported, or undefined if it isn't two nonnegative safe integers. */
 export declare function parseInferenceResult(result: unknown): InferenceResult | undefined;
 /**

package/dist/resource/inference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../../src/resource/inference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,kCAAkC,EAAE,0BAA0B,EAAE,yCAAyC,EAAE,MAAM,iBAAiB,CAAC;AAEjJ,8FAA8F;AAC9F,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAIhD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC3B,iCAAiC,EAAE,MAAM,CAAC;IAC1C,kCAAkC,EAAE,MAAM,CAAC;CAC9C;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,yCAAyC,GAAG,SAAS,GAAG,QAAQ,IAAI,kCAAkC,CAEnJ;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,GAAG,OAAO,CAEzF;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAQxG;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,UAAU,EAAE,6BAA6B,EAAE,GAAG,MAAM,GAAG,SAAS,CAG9F;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAajF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,0BAA0B,GAAG,IAAI,CAsB9E"}
+{"version":3,"file":"inference.d.ts","sourceRoot":"","sources":["../../src/resource/inference.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,KAAK,EAAE,kCAAkC,EAAE,0BAA0B,EAAE,yCAAyC,EAAE,MAAM,iBAAiB,CAAC;AAEjJ,8FAA8F;AAC9F,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAIhD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACxB;AAED,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;CACzB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC3B,iCAAiC,EAAE,MAAM,CAAC;IAC1C,kCAAkC,EAAE,MAAM,CAAC;CAC9C;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,yCAAyC,GAAG,SAAS,GAAG,QAAQ,IAAI,kCAAkC,CAEnJ;AAED,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,GAAG,OAAO,CAEzF;AAMD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAQxG;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,UAAU,EAAE,6BAA6B,EAAE,GAAG,MAAM,GAAG,SAAS,CAG9F;AAED,8HAA8H;AAC9H,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,0BAA0B,EAAE,UAAU,EAAE,6BAA6B,EAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAOlJ;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAajF;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,0BAA0B,GAAG,IAAI,CAsB9E"}

package/dist/resource/inference.js

@@ -29,6 +29,16 @@ export function parseMaxTokens(parameters) {
     const value = parameters.find(parameter => parameter.name === MAX_TOKENS_PARAMETER)?.value;
     return Number.isInteger(value) && value > 0 && value <= INT32_MAX ? value : undefined;
 }
+/** The function's own input-token estimate, or undefined if its estimator failed or returned something other than a count. */
+export async function estimateInputTokens(fn, parameters) {
+    try {
+        const inputTokens = await fn.estimateInputTokens?.(parameters);
+        return Number.isSafeInteger(inputTokens) && inputTokens >= 0 ? inputTokens : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** The usage an inference `exec` reported, or undefined if it isn't two nonnegative safe integers. */
 export function parseInferenceResult(result) {
     if (typeof result !== 'object' || result === null || !('usage' in result)) {

package/dist/resource/invoker.d.ts

@@ -1,4 +1,5 @@
 import { Resource, ResourceFunctionCallParameter, ResourceInvoker } from "requestscript";
+import type { OperatorClient } from "../client/operatorClient.js";
 import type { GrantService } from "../grant/service.js";
 import { type InferenceUsage } from "./inference.js";
 import { ResourceRepository, type StellariumInferencePaymentManifest } from "./repository.js";
@@ -11,6 +12,8 @@ export interface PaymentVoucher {
     expiresAt: string;
     invocationHash: string;
     publicKey: string;
+    /** Set for a call made by a script run billed to an API client: the run's hold pays instead of this node's organization. */
+    runId?: string;
 }
 /**
  * A voucher for an inference function. It signs the provider's per-million-token rates and the call's
@@ -30,6 +33,8 @@ export interface InferencePaymentVoucher {
     expiresAt: string;
     invocationHash: string;
     publicKey: string;
+    /** Set for a call made by a script run billed to an API client: the run's hold pays instead of this node's organization. */
+    runId?: string;
 }
 /** What a provider's `POST /v1/run/resource/estimate` answers. */
 export interface InferenceEstimate {
@@ -54,12 +59,14 @@ export declare function paymentVoucherPayload(voucher: Omit<PaymentVoucher, "sig
     expiresAt: string;
     invocationHash: string;
     publicKey: string;
+    runId?: string;
 };
 /**
  * The object `createInferenceVoucher` signs: every inference voucher field except `signature`.
  * Key order is part of the signed bytes.
  */
 export declare function inferenceVoucherPayload(voucher: Omit<InferencePaymentVoucher, "signature">): {
+    runId?: string;
     kind: "inference";
     requestId: string;
     invocationId: string;
@@ -82,6 +89,16 @@ export declare const EXTERNAL_INVOKE_BASE_DELAY_MS = 500;
 export declare const EXTERNAL_INVOKE_TIMEOUT_MS = 30000;
 /** Per attempt, for calls to inference functions. Every attempt fits within `INFERENCE_VOUCHER_LIFETIME_MS`. */
 export declare const INFERENCE_INVOKE_TIMEOUT_MS = 120000;
+/** A script run billed to another organization's API client. Its paid calls draw on the run's hold. */
+export interface RunContext {
+    runId: string;
+}
+/** How a node settles its own paid functions when a billed run calls them. */
+export interface LocalSettlement {
+    operatorClient: OperatorClient;
+    /** The organization this node's functions pay. */
+    organizationId?: string;
+}
 export declare class CombinationResourceInvoker implements ResourceInvoker {
     private readonly resourceRepository;
     private readonly costLimitMicroUsd;
@@ -89,11 +106,19 @@ export declare class CombinationResourceInvoker implements ResourceInvoker {
     private readonly privateKey;
     private readonly grantService?;
     private readonly inferenceCostLimitMicroUsd;
+    private readonly localSettlement?;
     /**
      * Without a `grantService`, calls to restricted remote functions fail.
      * `inferenceCostLimitMicroUsd` caps an inference voucher's `maxAmount`, and defaults to `costLimitMicroUsd`.
+     * Without `localSettlement`, a billed run can't call this node's own paid functions.
+     */
+    constructor(resourceRepository: ResourceRepository, costLimitMicroUsd: number, publicKey: string, privateKey: string, grantService?: GrantService | undefined, inferenceCostLimitMicroUsd?: number, localSettlement?: LocalSettlement | undefined);
+    /**
+     * An invoker for one billed run. Its paid calls, remote or to this node's own paid functions, carry
+     * the run's id, so the run's hold pays for them. The run's hold limits what they cost, in place of the
+     * cost limits.
      */
-    constructor(resourceRepository: ResourceRepository, costLimitMicroUsd: number, publicKey: string, privateKey: string, grantService?: GrantService | undefined, inferenceCostLimitMicroUsd?: number);
+    forRun(run: RunContext): ResourceInvoker;
     /**
      * Invoke a function on a resource.
      * If the resource has a baseUrl, it will be invoked as a remote function.
@@ -114,9 +139,18 @@ export declare class CombinationResourceInvoker implements ResourceInvoker {
         } | null;
         usage?: InferenceUsage;
     }>;
+    private invokeIn;
+    private execLocal;
+    /**
+     * Calls one of this node's paid functions for a billed run: signs a voucher with the run's id that pays
+     * this node's organization, then authorizes, runs and settles it as `POST /v1/run/resource` would.
+     */
+    private invokeLocalPaid;
     /** Asks the provider what a call to a paid inference function will cost at most. */
     private estimate;
-    createPaymentVoucher(recipientOrganizationId: string, amount: number, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[]): PaymentVoucher;
-    createInferenceVoucher(manifest: StellariumInferencePaymentManifest, maxAmount: number, maxTokens: number, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[]): InferencePaymentVoucher;
+    /** With `runId`, the voucher is paid from that run's hold. */
+    createPaymentVoucher(recipientOrganizationId: string, amount: number, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[], runId?: string): PaymentVoucher;
+    /** With `runId`, the voucher is paid from that run's hold. */
+    createInferenceVoucher(manifest: StellariumInferencePaymentManifest, maxAmount: number, maxTokens: number, resourcePath: string, resourceName: string, functionName: string, parameters: ResourceFunctionCallParameter[], runId?: string): InferencePaymentVoucher;
 }
 //# sourceMappingURL=invoker.d.ts.map

package/dist/resource/invoker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/resource/invoker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"invoker.d.ts","sourceRoot":"","sources":["../../src/resource/invoker.ts"],"names":[],"mappings":"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"}

package/dist/resource/invoker.js

@@ -1,5 +1,6 @@
 import { hashData, signData } from "../crypto/utils.js";
-import { inferenceCharge, isInferenceFunction, isInferenceManifest, parseInferenceResult, parseMaxTokens } from "./inference.js";
+import { estimateInputTokens, inferenceCharge, isInferenceFunction, isInferenceManifest, parseInferenceResult, parseMaxTokens } from "./inference.js";
+import { settlePaidCall } from "./settlement.js";
 /**
  * Hash binding a voucher to one function call. Providers recompute it from the
  * request they receive and compare it to `voucher.invocationHash`.
@@ -14,7 +15,11 @@ export function invocationHash(resourcePath, resourceName, functionName, paramet
  */
 export function paymentVoucherPayload(voucher) {
     const { requestId, invocationId, amount, recipientOrganizationId, expiresAt, invocationHash, publicKey } = voucher;
-    return { requestId, invocationId, amount, recipientOrganizationId, expiresAt, invocationHash, publicKey };
+    return { requestId, invocationId, amount, recipientOrganizationId, expiresAt, invocationHash, publicKey, ...runPayload(voucher.runId) };
+}
+/** `runId` is signed last, and only when set, so a voucher without one signs the same bytes as before it existed. */
+function runPayload(runId) {
+    return runId === undefined ? {} : { runId };
 }
 /**
  * The object `createInferenceVoucher` signs: every inference voucher field except `signature`.
@@ -22,7 +27,7 @@ export function paymentVoucherPayload(voucher) {
  */
 export function inferenceVoucherPayload(voucher) {
     const { kind, requestId, invocationId, maxAmount, inputCostMicroUsdPerMillionTokens, outputCostMicroUsdPerMillionTokens, maxTokens, recipientOrganizationId, expiresAt, invocationHash, publicKey } = voucher;
-    return { kind, requestId, invocationId, maxAmount, inputCostMicroUsdPerMillionTokens, outputCostMicroUsdPerMillionTokens, maxTokens, recipientOrganizationId, expiresAt, invocationHash, publicKey };
+    return { kind, requestId, invocationId, maxAmount, inputCostMicroUsdPerMillionTokens, outputCostMicroUsdPerMillionTokens, maxTokens, recipientOrganizationId, expiresAt, invocationHash, publicKey, ...runPayload(voucher.runId) };
 }
 export function isInferenceVoucher(voucher) {
     return voucher.kind === 'inference';
@@ -68,17 +73,28 @@ export class CombinationResourceInvoker {
     privateKey;
     grantService;
     inferenceCostLimitMicroUsd;
+    localSettlement;
     /**
      * Without a `grantService`, calls to restricted remote functions fail.
      * `inferenceCostLimitMicroUsd` caps an inference voucher's `maxAmount`, and defaults to `costLimitMicroUsd`.
+     * Without `localSettlement`, a billed run can't call this node's own paid functions.
      */
-    constructor(resourceRepository, costLimitMicroUsd, publicKey, privateKey, grantService, inferenceCostLimitMicroUsd = costLimitMicroUsd) {
+    constructor(resourceRepository, costLimitMicroUsd, publicKey, privateKey, grantService, inferenceCostLimitMicroUsd = costLimitMicroUsd, localSettlement) {
         this.resourceRepository = resourceRepository;
         this.costLimitMicroUsd = costLimitMicroUsd;
         this.publicKey = publicKey;
         this.privateKey = privateKey;
         this.grantService = grantService;
         this.inferenceCostLimitMicroUsd = inferenceCostLimitMicroUsd;
+        this.localSettlement = localSettlement;
+    }
+    /**
+     * An invoker for one billed run. Its paid calls, remote or to this node's own paid functions, carry
+     * the run's id, so the run's hold pays for them. The run's hold limits what they cost, in place of the
+     * cost limits.
+     */
+    forRun(run) {
+        return { invoke: (resource, functionName, parameters) => this.invokeIn(resource, functionName, parameters, run) };
     }
     /**
      * Invoke a function on a resource.
@@ -94,6 +110,9 @@ export class CombinationResourceInvoker {
      * @returns The return value of the function
      */
     async invoke(resource, functionName, parameters) {
+        return this.invokeIn(resource, functionName, parameters, undefined);
+    }
+    async invokeIn(resource, functionName, parameters, run) {
         if (resource.metadata.baseUrl) {
             let requestBody = {
                 resourcePath: resource.path,
@@ -139,20 +158,20 @@ export class CombinationResourceInvoker {
                 if (inferenceCharge(manifest, estimate.inputTokens, maxTokens) !== estimate.maxAmount) {
                     return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: the provider's estimate doesn't match its advertised rates` } };
                 }
-                if (estimate.maxAmount > this.inferenceCostLimitMicroUsd) {
+                if (!run && estimate.maxAmount > this.inferenceCostLimitMicroUsd) {
                     throw new Error(`Function ${functionName} may cost up to ${estimate.maxAmount} micro-USD, which exceeds the inference cost limit of ${this.inferenceCostLimitMicroUsd} micro-USD`);
                 }
-                requestBody.paymentVoucher = this.createInferenceVoucher(manifest, estimate.maxAmount, maxTokens, resource.path, resource.name, functionName, parameters);
+                requestBody.paymentVoucher = this.createInferenceVoucher(manifest, estimate.maxAmount, maxTokens, resource.path, resource.name, functionName, parameters, run?.runId);
             }
             else if (manifest) {
                 console.log(`Resource function ${resource.name}.${functionName} has a payment manifest, creating payment voucher...`);
                 if (isInferenceManifest(manifest)) {
                     return { value: null, error: { message: `Failed to invoke ${resource.name}.${functionName}: it has per-token pricing but isn't an inference function` } };
                 }
-                if (manifest.costMicroUsd > this.costLimitMicroUsd) {
+                if (!run && manifest.costMicroUsd > this.costLimitMicroUsd) {
                     throw new Error(`Function ${functionName} cost ${manifest.costMicroUsd} micro-USD, which exceeds the cost limit of ${this.costLimitMicroUsd} micro-USD`);
                 }
-                requestBody.paymentVoucher = this.createPaymentVoucher(manifest.recipientOrganizationId, manifest.costMicroUsd, resource.path, resource.name, functionName, parameters);
+                requestBody.paymentVoucher = this.createPaymentVoucher(manifest.recipientOrganizationId, manifest.costMicroUsd, resource.path, resource.name, functionName, parameters, run?.runId);
             }
             // The voucher is created once and reused on every attempt, so the operator's
             // requestId/invocationId check prevents a retried call from being settled twice.
@@ -178,17 +197,57 @@ export class CombinationResourceInvoker {
             if (!fn) {
                 return { value: null, error: { message: `Function ${functionName} not found in resource ${resource.name}` } };
             }
-            const result = await fn.exec(parameters);
-            if (isInferenceFunction(fn)) {
-                const inferenceResult = parseInferenceResult(result);
-                if (!inferenceResult) {
-                    return { value: null, error: { message: `Inference function ${functionName} must return { value, usage: { inputTokens, outputTokens } }` } };
-                }
-                return { value: inferenceResult.value, error: null, usage: inferenceResult.usage };
+            // A billed run pays for this node's own paid functions as a remote caller would.
+            if (run && fn.paymentManifest) {
+                return this.invokeLocalPaid(resource, fn, parameters, run);
             }
-            return { value: result, error: null };
+            return this.execLocal(fn, parameters);
         }
     }
+    async execLocal(fn, parameters) {
+        const result = await fn.exec(parameters);
+        if (isInferenceFunction(fn)) {
+            const inferenceResult = parseInferenceResult(result);
+            if (!inferenceResult) {
+                return { value: null, error: { message: `Inference function ${fn.name} must return { value, usage: { inputTokens, outputTokens } }` } };
+            }
+            return { value: inferenceResult.value, error: null, usage: inferenceResult.usage };
+        }
+        return { value: result, error: null };
+    }
+    /**
+     * Calls one of this node's paid functions for a billed run: signs a voucher with the run's id that pays
+     * this node's organization, then authorizes, runs and settles it as `POST /v1/run/resource` would.
+     */
+    async invokeLocalPaid(resource, fn, parameters, run) {
+        const failed = (reason) => ({ value: null, error: { message: `Failed to invoke ${resource.name}.${fn.name}: ${reason}` } });
+        const organizationId = this.localSettlement?.organizationId;
+        if (!this.localSettlement || !organizationId) {
+            return failed('this node is not enrolled in an organization that can be paid');
+        }
+        const manifest = fn.paymentManifest;
+        let voucher;
+        if (isInferenceFunction(fn) && isInferenceManifest(manifest)) {
+            const maxTokens = parseMaxTokens(parameters);
+            if (maxTokens === undefined) {
+                return failed('maxTokens must be a positive int32');
+            }
+            const inputTokens = await estimateInputTokens(fn, parameters);
+            if (inputTokens === undefined) {
+                return failed('failed to estimate input tokens');
+            }
+            const maxAmount = inferenceCharge(manifest, inputTokens, maxTokens);
+            voucher = this.createInferenceVoucher({ ...manifest, recipientOrganizationId: organizationId }, maxAmount, maxTokens, resource.path, resource.name, fn.name, parameters, run.runId);
+        }
+        else if (!isInferenceManifest(manifest)) {
+            voucher = this.createPaymentVoucher(organizationId, manifest.costMicroUsd, resource.path, resource.name, fn.name, parameters, run.runId);
+        }
+        else {
+            return failed('it has per-token pricing but isn\'t an inference function');
+        }
+        const result = await settlePaidCall(this.localSettlement.operatorClient, voucher, () => this.execLocal(fn, parameters), (error, message) => console.error(message, error));
+        return 'refused' in result ? failed(result.refused.error) : result;
+    }
     /** Asks the provider what a call to a paid inference function will cost at most. */
     async estimate(url, target, chain) {
         let response;
@@ -213,15 +272,22 @@ export class CombinationResourceInvoker {
         }
         return { inputTokens: inputTokens, maxAmount: maxAmount };
     }
-    createPaymentVoucher(recipientOrganizationId, amount, resourcePath, resourceName, functionName, parameters) {
-        const requestId = crypto.randomUUID();
-        const invocationId = crypto.randomUUID();
-        const expiresAt = new Date(Date.now() + PAYMENT_VOUCHER_LIFETIME_MS).toISOString();
-        const hash = invocationHash(resourcePath, resourceName, functionName, parameters);
-        const signature = signData(paymentVoucherPayload({ requestId, invocationId, amount, recipientOrganizationId, expiresAt, invocationHash: hash, publicKey: this.publicKey }), this.privateKey);
-        return { requestId, invocationId, amount, recipientOrganizationId, signature, expiresAt, invocationHash: hash, publicKey: this.publicKey };
+    /** With `runId`, the voucher is paid from that run's hold. */
+    createPaymentVoucher(recipientOrganizationId, amount, resourcePath, resourceName, functionName, parameters, runId) {
+        const unsigned = {
+            requestId: crypto.randomUUID(),
+            invocationId: crypto.randomUUID(),
+            amount,
+            recipientOrganizationId,
+            expiresAt: new Date(Date.now() + PAYMENT_VOUCHER_LIFETIME_MS).toISOString(),
+            invocationHash: invocationHash(resourcePath, resourceName, functionName, parameters),
+            publicKey: this.publicKey,
+            ...runPayload(runId),
+        };
+        return { ...unsigned, signature: signData(paymentVoucherPayload(unsigned), this.privateKey) };
     }
-    createInferenceVoucher(manifest, maxAmount, maxTokens, resourcePath, resourceName, functionName, parameters) {
+    /** With `runId`, the voucher is paid from that run's hold. */
+    createInferenceVoucher(manifest, maxAmount, maxTokens, resourcePath, resourceName, functionName, parameters, runId) {
         const unsigned = {
             kind: 'inference',
             requestId: crypto.randomUUID(),
@@ -234,6 +300,7 @@ export class CombinationResourceInvoker {
             expiresAt: new Date(Date.now() + INFERENCE_VOUCHER_LIFETIME_MS).toISOString(),
             invocationHash: invocationHash(resourcePath, resourceName, functionName, parameters),
             publicKey: this.publicKey,
+            ...runPayload(runId),
         };
         return { ...unsigned, signature: signData(inferenceVoucherPayload(unsigned), this.privateKey) };
     }

package/dist/resource/settlement.d.ts

@@ -0,0 +1,25 @@
+import type { OperatorClient } from "../client/operatorClient.js";
+import { type InferenceUsage } from "./inference.js";
+import { type InferencePaymentVoucher, type PaymentVoucher } from "./invoker.js";
+/** What a resource function call evaluates to, with an inference function's usage. */
+export interface InvokeResult {
+    value: unknown;
+    error: {
+        message: string;
+    } | null;
+    usage?: InferenceUsage;
+}
+/** The operator refused to hold the voucher, so the call didn't run. */
+export interface PaymentRefusal {
+    refused: {
+        status: number;
+        error: string;
+    };
+}
+/**
+ * Runs a paid call: holds the voucher's amount with the operator first, so a paid function never runs
+ * unpaid, then runs `call` and captures the voucher, or releases it for a failed or free call. Settlement is
+ * scheduled after returning, so it doesn't delay the caller, and failures go to `onSettleError`.
+ */
+export declare function settlePaidCall(operatorClient: OperatorClient, voucher: PaymentVoucher | InferencePaymentVoucher, call: () => Promise<InvokeResult>, onSettleError: (error: unknown, message: string) => void): Promise<InvokeResult | PaymentRefusal>;
+//# sourceMappingURL=settlement.d.ts.map

package/dist/resource/settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../../src/resource/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAAE,KAAK,uBAAuB,EAAsB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAErG,sFAAsF;AACtF,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClC,KAAK,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAYD;;;;GAIG;AACH,wBAAsB,cAAc,CAChC,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,cAAc,GAAG,uBAAuB,EACjD,IAAI,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,EACjC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,GACzD,OAAO,CAAC,YAAY,GAAG,cAAc,CAAC,CAuCxC"}