@vallum/sdk 0.0.0-prerelease

package/dist/contracts/payPerCall.js

@@ -0,0 +1,110 @@
+import { approvePayPerCallReceipt, completePayPerCallReceipt, createPayPerCallReceipt, denyPayPerCallReceipt, failPayPerCallReceipt, sponsorPayPerCallReceipt, submitPayPerCallReceipt, } from "@vallum/receipts";
+import { requestSponsoredAction } from "../requestSponsoredAction.js";
+export async function callPaidTool(options) {
+    const now = options.now?.() ?? new Date();
+    const attempted = createPayPerCallReceipt({
+        receiptId: options.receiptId,
+        manifestId: options.manifest.idempotencyKey,
+        idempotencyKey: options.manifest.idempotencyKey,
+        agentId: options.manifest.agent.id,
+        ownerId: options.manifest.owner.id,
+        providerId: options.providerId,
+        toolName: options.toolName,
+        amount: options.amount,
+        createdAt: now,
+    });
+    const sponsoredAction = await requestSponsoredAction({
+        baseUrl: options.gatewayBaseUrl,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+        manifest: options.manifest,
+    });
+    if (!sponsoredAction.approved) {
+        return {
+            paid: false,
+            sponsoredAction,
+            receipt: denyPayPerCallReceipt(attempted, {
+                at: now,
+                reason: sponsoredAction.decision.reasonCode,
+            }),
+        };
+    }
+    const sponsored = sponsorPayPerCallReceipt(approvePayPerCallReceipt(attempted, { at: now }), {
+        at: now,
+        sponsorshipId: sponsoredAction.mockSponsorshipId,
+    });
+    const payment = await confirmPayment(options.confirmPayment);
+    if (!payment.ok) {
+        return {
+            paid: false,
+            sponsoredAction,
+            receipt: failPayPerCallReceipt(sponsored, {
+                at: now,
+                reason: payment.reason,
+            }),
+        };
+    }
+    if (!isNonEmptyString(payment.transactionDigest)) {
+        return {
+            paid: false,
+            sponsoredAction,
+            receipt: failPayPerCallReceipt(sponsored, {
+                at: now,
+                reason: "PAYMENT_CONFIRMATION_INVALID",
+            }),
+        };
+    }
+    const submitted = submitPayPerCallReceipt(sponsored, {
+        at: now,
+        transactionDigest: payment.transactionDigest,
+    });
+    const invocation = await invokeTool(options.invokeTool);
+    if (!invocation.ok) {
+        return {
+            paid: false,
+            sponsoredAction,
+            receipt: failPayPerCallReceipt(submitted, {
+                at: now,
+                reason: invocation.reason,
+            }),
+        };
+    }
+    if (!isNonEmptyString(invocation.result.resultHash)) {
+        return {
+            paid: false,
+            sponsoredAction,
+            receipt: failPayPerCallReceipt(submitted, {
+                at: now,
+                reason: "TOOL_RESULT_HASH_INVALID",
+            }),
+        };
+    }
+    return {
+        paid: true,
+        sponsoredAction,
+        result: invocation.result.result,
+        receipt: completePayPerCallReceipt(submitted, {
+            at: now,
+            resultHash: invocation.result.resultHash,
+        }),
+    };
+}
+async function confirmPayment(confirmPaymentFn) {
+    try {
+        return await confirmPaymentFn();
+    }
+    catch {
+        return { ok: false, reason: "PAYMENT_CONFIRMATION_FAILED" };
+    }
+}
+async function invokeTool(invokeToolFn) {
+    try {
+        return { ok: true, result: await invokeToolFn() };
+    }
+    catch {
+        return { ok: false, reason: "TOOL_INVOCATION_FAILED" };
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}

package/dist/contracts/reputationReceipt.d.ts

@@ -0,0 +1,39 @@
+import type { AgentTransactionManifest } from "@vallum/manifest";
+import { type ReceiptAmount, type ReputationReceipt } from "@vallum/receipts";
+import type { SponsoredActionResult } from "../types.js";
+export type ReputationEvidence = {
+    readonly ok: true;
+    readonly transactionDigest: string;
+    readonly score: number;
+    readonly evidenceHash: string;
+    readonly attestationHash: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface AttestReputationOptions {
+    readonly gatewayBaseUrl: string;
+    readonly apiKey: string;
+    readonly manifest: AgentTransactionManifest;
+    readonly receiptId: string;
+    readonly issuerId: string;
+    readonly subjectId: string;
+    readonly interactionId: string;
+    readonly criteriaHash: string;
+    readonly amount: ReceiptAmount;
+    readonly collectEvidence: () => Promise<ReputationEvidence>;
+    readonly now?: () => Date;
+    readonly fetchImpl?: typeof fetch;
+}
+export type AttestReputationResult = {
+    readonly attested: true;
+    readonly sponsoredAction: Extract<SponsoredActionResult, {
+        approved: true;
+    }>;
+    readonly receipt: ReputationReceipt;
+} | {
+    readonly attested: false;
+    readonly sponsoredAction: SponsoredActionResult;
+    readonly receipt: ReputationReceipt;
+};
+export declare function attestReputation(options: AttestReputationOptions): Promise<AttestReputationResult>;

package/dist/contracts/reputationReceipt.js

@@ -0,0 +1,94 @@
+import { approveReputationReceipt, completeReputationReceipt, createReputationReceipt, denyReputationReceipt, failReputationReceipt, sponsorReputationReceipt, submitReputationReceipt, } from "@vallum/receipts";
+import { requestSponsoredAction } from "../requestSponsoredAction.js";
+export async function attestReputation(options) {
+    const now = options.now?.() ?? new Date();
+    const attempted = createReputationReceipt({
+        receiptId: options.receiptId,
+        manifestId: options.manifest.idempotencyKey,
+        idempotencyKey: options.manifest.idempotencyKey,
+        agentId: options.manifest.agent.id,
+        ownerId: options.manifest.owner.id,
+        issuerId: options.issuerId,
+        subjectId: options.subjectId,
+        interactionId: options.interactionId,
+        criteriaHash: options.criteriaHash,
+        amount: options.amount,
+        createdAt: now,
+    });
+    const sponsoredAction = await requestSponsoredAction({
+        baseUrl: options.gatewayBaseUrl,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+        manifest: options.manifest,
+    });
+    if (!sponsoredAction.approved) {
+        return {
+            attested: false,
+            sponsoredAction,
+            receipt: denyReputationReceipt(attempted, {
+                at: now,
+                reason: sponsoredAction.decision.reasonCode,
+            }),
+        };
+    }
+    const sponsored = sponsorReputationReceipt(approveReputationReceipt(attempted, { at: now }), {
+        at: now,
+        sponsorshipId: sponsoredAction.mockSponsorshipId,
+    });
+    const evidence = await collectEvidence(options.collectEvidence);
+    if (!evidence.ok) {
+        return {
+            attested: false,
+            sponsoredAction,
+            receipt: failReputationReceipt(sponsored, {
+                at: now,
+                reason: evidence.reason,
+            }),
+        };
+    }
+    if (!Number.isInteger(evidence.score)
+        || evidence.score < 1
+        || evidence.score > 5
+        || !isNonEmptyString(evidence.transactionDigest)
+        || !isSafeHashReference(evidence.evidenceHash)
+        || !isSafeHashReference(evidence.attestationHash)) {
+        return {
+            attested: false,
+            sponsoredAction,
+            receipt: failReputationReceipt(sponsored, {
+                at: now,
+                reason: "REPUTATION_EVIDENCE_INVALID",
+            }),
+        };
+    }
+    const submitted = submitReputationReceipt(sponsored, {
+        at: now,
+        transactionDigest: evidence.transactionDigest,
+    });
+    return {
+        attested: true,
+        sponsoredAction,
+        receipt: completeReputationReceipt(submitted, {
+            at: now,
+            score: evidence.score,
+            evidenceHash: evidence.evidenceHash,
+            attestationHash: evidence.attestationHash,
+        }),
+    };
+}
+async function collectEvidence(collectEvidenceFn) {
+    try {
+        return await collectEvidenceFn();
+    }
+    catch {
+        return { ok: false, reason: "REPUTATION_EVIDENCE_FAILED" };
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function isSafeHashReference(value) {
+    return isNonEmptyString(value)
+        && /^sha256:[A-Za-z0-9._:-]+$/.test(value)
+        && !/(private prompt|review payload|bearer|signer_ref|payment credential|privateKey|mnemonic|seed)/i.test(value);
+}

package/dist/contracts/serviceBounty.d.ts

@@ -0,0 +1,38 @@
+import type { AgentTransactionManifest } from "@vallum/manifest";
+import { type ReceiptAmount, type ServiceBountyReceipt } from "@vallum/receipts";
+import type { SponsoredActionResult } from "../types.js";
+export type ServiceBountyCompletionProof = {
+    readonly ok: true;
+    readonly transactionDigest: string;
+    readonly completionProofHash: string;
+    readonly releaseProofHash: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface FulfillServiceBountyOptions {
+    readonly gatewayBaseUrl: string;
+    readonly apiKey: string;
+    readonly manifest: AgentTransactionManifest;
+    readonly receiptId: string;
+    readonly requesterId: string;
+    readonly providerId: string;
+    readonly bountyId: string;
+    readonly deliverableHash: string;
+    readonly amount: ReceiptAmount;
+    readonly completeWork: () => Promise<ServiceBountyCompletionProof>;
+    readonly now?: () => Date;
+    readonly fetchImpl?: typeof fetch;
+}
+export type FulfillServiceBountyResult = {
+    readonly released: true;
+    readonly sponsoredAction: Extract<SponsoredActionResult, {
+        approved: true;
+    }>;
+    readonly receipt: ServiceBountyReceipt;
+} | {
+    readonly released: false;
+    readonly sponsoredAction: SponsoredActionResult;
+    readonly receipt: ServiceBountyReceipt;
+};
+export declare function fulfillServiceBounty(options: FulfillServiceBountyOptions): Promise<FulfillServiceBountyResult>;

package/dist/contracts/serviceBounty.js

@@ -0,0 +1,88 @@
+import { approveServiceBountyReceipt, completeServiceBountyReceipt, createServiceBountyReceipt, denyServiceBountyReceipt, failServiceBountyReceipt, releaseServiceBountyReceipt, sponsorServiceBountyReceipt, submitServiceBountyReceipt, } from "@vallum/receipts";
+import { requestSponsoredAction } from "../requestSponsoredAction.js";
+export async function fulfillServiceBounty(options) {
+    const now = options.now?.() ?? new Date();
+    const attempted = createServiceBountyReceipt({
+        receiptId: options.receiptId,
+        manifestId: options.manifest.idempotencyKey,
+        idempotencyKey: options.manifest.idempotencyKey,
+        agentId: options.manifest.agent.id,
+        ownerId: options.manifest.owner.id,
+        requesterId: options.requesterId,
+        providerId: options.providerId,
+        bountyId: options.bountyId,
+        deliverableHash: options.deliverableHash,
+        amount: options.amount,
+        createdAt: now,
+    });
+    const sponsoredAction = await requestSponsoredAction({
+        baseUrl: options.gatewayBaseUrl,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+        manifest: options.manifest,
+    });
+    if (!sponsoredAction.approved) {
+        return {
+            released: false,
+            sponsoredAction,
+            receipt: denyServiceBountyReceipt(attempted, {
+                at: now,
+                reason: sponsoredAction.decision.reasonCode,
+            }),
+        };
+    }
+    const sponsored = sponsorServiceBountyReceipt(approveServiceBountyReceipt(attempted, { at: now }), {
+        at: now,
+        sponsorshipId: sponsoredAction.mockSponsorshipId,
+    });
+    const proof = await completeWork(options.completeWork);
+    if (!proof.ok) {
+        return {
+            released: false,
+            sponsoredAction,
+            receipt: failServiceBountyReceipt(sponsored, {
+                at: now,
+                reason: proof.reason,
+            }),
+        };
+    }
+    if (!isNonEmptyString(proof.transactionDigest)
+        || !isNonEmptyString(proof.completionProofHash)
+        || !isNonEmptyString(proof.releaseProofHash)) {
+        return {
+            released: false,
+            sponsoredAction,
+            receipt: failServiceBountyReceipt(sponsored, {
+                at: now,
+                reason: "COMPLETION_PROOF_INVALID",
+            }),
+        };
+    }
+    const submitted = submitServiceBountyReceipt(sponsored, {
+        at: now,
+        transactionDigest: proof.transactionDigest,
+    });
+    const completed = completeServiceBountyReceipt(submitted, {
+        at: now,
+        completionProofHash: proof.completionProofHash,
+    });
+    return {
+        released: true,
+        sponsoredAction,
+        receipt: releaseServiceBountyReceipt(completed, {
+            at: now,
+            releaseProofHash: proof.releaseProofHash,
+        }),
+    };
+}
+async function completeWork(completeWorkFn) {
+    try {
+        return await completeWorkFn();
+    }
+    catch {
+        return { ok: false, reason: "COMPLETION_PROOF_FAILED" };
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}

package/dist/contracts/subscription.d.ts

@@ -0,0 +1,69 @@
+import type { AgentTransactionManifest } from "@vallum/manifest";
+import { type ReceiptAmount, type SubscriptionReceipt } from "@vallum/receipts";
+import type { SponsoredActionResult } from "../types.js";
+export type SubscriptionActivationProof = {
+    readonly ok: true;
+    readonly transactionDigest: string;
+    readonly activationProofHash: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export type SubscriptionRenewalProof = {
+    readonly ok: true;
+    readonly transactionDigest: string;
+    readonly renewalProofHash: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export interface StartSubscriptionOptions {
+    readonly gatewayBaseUrl: string;
+    readonly apiKey: string;
+    readonly manifest: AgentTransactionManifest;
+    readonly receiptId: string;
+    readonly subscriberId: string;
+    readonly providerId: string;
+    readonly planId: string;
+    readonly termsHash: string;
+    readonly periodStart: string;
+    readonly periodEnd: string;
+    readonly amount: ReceiptAmount;
+    readonly activate: () => Promise<SubscriptionActivationProof>;
+    readonly now?: () => Date;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface RenewSubscriptionOptions {
+    readonly gatewayBaseUrl: string;
+    readonly apiKey: string;
+    readonly manifest: AgentTransactionManifest;
+    readonly receipt: SubscriptionReceipt;
+    readonly periodEnd: string;
+    readonly renew: () => Promise<SubscriptionRenewalProof>;
+    readonly now?: () => Date;
+    readonly fetchImpl?: typeof fetch;
+}
+export type StartSubscriptionResult = {
+    readonly active: true;
+    readonly sponsoredAction: Extract<SponsoredActionResult, {
+        approved: true;
+    }>;
+    readonly receipt: SubscriptionReceipt;
+} | {
+    readonly active: false;
+    readonly sponsoredAction: SponsoredActionResult;
+    readonly receipt: SubscriptionReceipt;
+};
+export type RenewSubscriptionResult = {
+    readonly renewed: true;
+    readonly sponsoredAction: Extract<SponsoredActionResult, {
+        approved: true;
+    }>;
+    readonly receipt: SubscriptionReceipt;
+} | {
+    readonly renewed: false;
+    readonly sponsoredAction: SponsoredActionResult;
+    readonly receipt: SubscriptionReceipt;
+};
+export declare function startSubscription(options: StartSubscriptionOptions): Promise<StartSubscriptionResult>;
+export declare function renewSubscription(options: RenewSubscriptionOptions): Promise<RenewSubscriptionResult>;

package/dist/contracts/subscription.js

@@ -0,0 +1,148 @@
+import { activateSubscriptionReceipt, approveSubscriptionReceipt, createSubscriptionReceipt, denySubscriptionReceipt, failSubscriptionReceipt, renewSubscriptionReceipt as renewSubscriptionReceiptState, sponsorSubscriptionReceipt, submitSubscriptionReceipt, } from "@vallum/receipts";
+import { requestSponsoredAction } from "../requestSponsoredAction.js";
+export async function startSubscription(options) {
+    const now = options.now?.() ?? new Date();
+    const attempted = createSubscriptionReceipt({
+        receiptId: options.receiptId,
+        manifestId: options.manifest.idempotencyKey,
+        idempotencyKey: options.manifest.idempotencyKey,
+        agentId: options.manifest.agent.id,
+        ownerId: options.manifest.owner.id,
+        subscriberId: options.subscriberId,
+        providerId: options.providerId,
+        planId: options.planId,
+        termsHash: options.termsHash,
+        periodStart: options.periodStart,
+        periodEnd: options.periodEnd,
+        amount: options.amount,
+        createdAt: now,
+    });
+    const sponsoredAction = await requestSponsoredAction({
+        baseUrl: options.gatewayBaseUrl,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+        manifest: options.manifest,
+    });
+    if (!sponsoredAction.approved) {
+        return {
+            active: false,
+            sponsoredAction,
+            receipt: denySubscriptionReceipt(attempted, {
+                at: now,
+                reason: sponsoredAction.decision.reasonCode,
+            }),
+        };
+    }
+    const sponsored = sponsorSubscriptionReceipt(approveSubscriptionReceipt(attempted, { at: now }), {
+        at: now,
+        sponsorshipId: sponsoredAction.mockSponsorshipId,
+    });
+    const proof = await collectActivationProof(options.activate);
+    if (!proof.ok) {
+        return {
+            active: false,
+            sponsoredAction,
+            receipt: failSubscriptionReceipt(sponsored, {
+                at: now,
+                reason: proof.reason,
+            }),
+        };
+    }
+    if (!isNonEmptyString(proof.transactionDigest) || !isSafeHashReference(proof.activationProofHash)) {
+        return {
+            active: false,
+            sponsoredAction,
+            receipt: failSubscriptionReceipt(sponsored, {
+                at: now,
+                reason: "SUBSCRIPTION_PROOF_INVALID",
+            }),
+        };
+    }
+    const submitted = submitSubscriptionReceipt(sponsored, {
+        at: now,
+        transactionDigest: proof.transactionDigest,
+    });
+    return {
+        active: true,
+        sponsoredAction,
+        receipt: activateSubscriptionReceipt(submitted, {
+            at: now,
+            activationProofHash: proof.activationProofHash,
+        }),
+    };
+}
+export async function renewSubscription(options) {
+    const now = options.now?.() ?? new Date();
+    const sponsoredAction = await requestSponsoredAction({
+        baseUrl: options.gatewayBaseUrl,
+        apiKey: options.apiKey,
+        fetchImpl: options.fetchImpl,
+        manifest: options.manifest,
+    });
+    if (!sponsoredAction.approved) {
+        return {
+            renewed: false,
+            sponsoredAction,
+            receipt: failSubscriptionReceipt(options.receipt, {
+                at: now,
+                reason: sponsoredAction.decision.reasonCode,
+            }),
+        };
+    }
+    const proof = await collectRenewalProof(options.renew);
+    if (!proof.ok) {
+        return {
+            renewed: false,
+            sponsoredAction,
+            receipt: failSubscriptionReceipt(options.receipt, {
+                at: now,
+                reason: proof.reason,
+            }),
+        };
+    }
+    if (!isNonEmptyString(proof.transactionDigest) || !isSafeHashReference(proof.renewalProofHash)) {
+        return {
+            renewed: false,
+            sponsoredAction,
+            receipt: failSubscriptionReceipt(options.receipt, {
+                at: now,
+                reason: "SUBSCRIPTION_PROOF_INVALID",
+            }),
+        };
+    }
+    return {
+        renewed: true,
+        sponsoredAction,
+        receipt: renewSubscriptionReceiptState(options.receipt, {
+            at: now,
+            periodEnd: options.periodEnd,
+            renewalProofHash: proof.renewalProofHash,
+            sponsorshipId: sponsoredAction.mockSponsorshipId,
+            transactionDigest: proof.transactionDigest,
+        }),
+    };
+}
+async function collectActivationProof(activate) {
+    try {
+        return await activate();
+    }
+    catch {
+        return { ok: false, reason: "SUBSCRIPTION_PROOF_FAILED" };
+    }
+}
+async function collectRenewalProof(renew) {
+    try {
+        return await renew();
+    }
+    catch {
+        return { ok: false, reason: "SUBSCRIPTION_PROOF_FAILED" };
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function isSafeHashReference(value) {
+    return isNonEmptyString(value)
+        && /^sha256:[A-Za-z0-9._:-]+$/.test(value)
+        && !/(private prompt|review payload|bearer|access-token|signer_ref|payment credential|privateKey|mnemonic|seed)/i.test(value);
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class VallumError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, body?: unknown | undefined);
+}
+export declare class VallumPolicyError extends VallumError {
+    readonly reasonCode?: string | undefined;
+    constructor(message: string, reasonCode?: string | undefined, status?: number, body?: unknown);
+}
+export declare class VallumAuthError extends VallumError {
+    constructor(message: string, status?: number, body?: unknown);
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+export class VallumError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "VallumError";
+    }
+}
+export class VallumPolicyError extends VallumError {
+    reasonCode;
+    constructor(message, reasonCode, status, body) {
+        super(message, status, body);
+        this.reasonCode = reasonCode;
+        this.name = "VallumPolicyError";
+    }
+}
+export class VallumAuthError extends VallumError {
+    constructor(message, status, body) {
+        super(message, status, body);
+        this.name = "VallumAuthError";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./IotaAgent.js";
+export * from "./client.js";
+export * from "./contracts/dataLicense.js";
+export * from "./contracts/openEscrow.js";
+export * from "./contracts/payPerCall.js";
+export * from "./contracts/reputationReceipt.js";
+export * from "./contracts/serviceBounty.js";
+export * from "./contracts/subscription.js";
+export * from "./errors.js";
+export * from "./requestSponsoredAction.js";
+export * from "./resolveAgent.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,12 @@
+export * from "./IotaAgent.js";
+export * from "./client.js";
+export * from "./contracts/dataLicense.js";
+export * from "./contracts/openEscrow.js";
+export * from "./contracts/payPerCall.js";
+export * from "./contracts/reputationReceipt.js";
+export * from "./contracts/serviceBounty.js";
+export * from "./contracts/subscription.js";
+export * from "./errors.js";
+export * from "./requestSponsoredAction.js";
+export * from "./resolveAgent.js";
+export * from "./types.js";

package/dist/requestSponsoredAction.d.ts

@@ -0,0 +1,2 @@
+import type { RequestSponsoredActionOptions, SponsoredActionResult } from "./types.js";
+export declare function requestSponsoredAction(options: RequestSponsoredActionOptions): Promise<SponsoredActionResult>;