402mob-merchant-sdk 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.7.0
+
+- Add buyer-signed withdrawal/replacement, optimistic response revisions, immutable history reads and closed-state validation for fresh-work requests. Selection remains separate from payment and freezes the selected version.
+
+- Add scoped, expiring merchant session create/list/revoke helpers; parent credential required and no wallet authority conferred.
+
+- Add optional immutable prepared-offer purchase metadata, public resource fields and a hash-verifying `getOfferTerms` reader. Introduced in 0.7.0.
+
+- Opt-in work agreement templates, private execution recovery and validated merchant event cursors. Introduced in 0.7.0.
+
+## 0.6.0
+
+- Accept semantically identical inspection-plan property order in proposal responses while rejecting unknown or substituted fields.
+
+- Add the protected inspection seller example: reviewed worker publication, exact capability search and explicit buyer-funded proposal construction; no automatic signing or payment.
+
+- Add explicit protected inspection proposals/handoffs and `ProtectedInspectionClient`, isolated from direct Work Tickets and JSON escrow. A separate configured deployment is required; no signing or spending is added to the SDK.
+
+- Retain requested format, selected payout, title and proposal note in the grant input. Reject unexpected handoff fields and substituted request lifetimes. Proposal publication checks the 32 KiB canonical grant-input limit.
+
+- Add typed fresh-work request, proposal, preflight decline and signed-selection helpers with response/handoff validation. Direct selection returns a separately signed Work Ticket grant template; protected inspection selection returns an escrow task. Neither selection authorizes payment.
+- Existing prepared-offer demand methods remain unchanged. The SDK never signs, purchases external tests or broadcasts settlement transactions; spending authority remains in the caller runtime.
+
 ## 0.5.0
 
 - Add `ProtectedWorkClient` for the separate experimental JSON escrow HTTP API, generated request/response types and schema checks. Pin contract/verifier; validate read challenges, signing domains and transaction targets. No signing, broadcasting, automatic retry or replica management. Includes protocol integration tests and an example. Earlier versions do not include these methods.

package/README.md

@@ -1,6 +1,9 @@
 # 402Mob Merchant SDK
 
-Version 0.5.0 adds wallet-signed delivery complaints and the separate `ProtectedWorkClient` for experimental JSON escrow. Install `402mob-merchant-sdk@0.5.0` for these methods; earlier versions do not include them.
+**Version 0.7.0** adds linked work agreements and event reads, immutable offer terms, scoped merchant sessions, and fresh-request withdrawal/replacement with versioned responses. Check the target server’s capabilities before calling new methods. The SDK never signs or spends for you.
+
+
+Version 0.5.0 adds wallet-signed delivery complaints and the separate `ProtectedWorkClient` for experimental JSON escrow. Install `402mob-merchant-sdk@0.7.0` for these methods; earlier versions do not include them.
 
 **Version 0.4.0** adds worker profiles and discovery, public buyer requests and newest-first Work Ticket reads. Upgrade from 0.3.1 to use these additions. Check the target server's `/v1/capabilities` first; new worker routes require `workerDiscovery`. See [CHANGELOG.md](./CHANGELOG.md).
 
@@ -39,7 +42,7 @@ If a message signer is locked, stop retries. `enrollWithTransaction` can use a s
 Install from npm:
 
 ```sh
-npm install 402mob-merchant-sdk@0.4.0
+npm install 402mob-merchant-sdk@0.7.0
 ```
 
 Version **0.4.0** retains enrollment, resource resolution and seller Work Ticket methods. Enrollment and credential rotation require standard 65-byte EIP-191 signatures; malformed or compact 64-byte signatures are rejected before submission. See the [npm package](https://www.npmjs.com/package/402mob-merchant-sdk) and [source](https://github.com/gggggggg424242/402mob-merchant-sdk).
@@ -254,7 +257,7 @@ To test a local build in another project, install the generated file with `npm i
 
 The SDK tests use mocked HTTP responses and type-check every bundled example. They do not contact `evidence.contact` or submit wallet transactions. Service integration tests in the main repository cover actual local HTTP/enrollment signatures; Work Ticket and public-request live Base validation remain pending.
 
-Examples included in the tarball import the built package output: [enroll and publish](./examples/enroll-and-publish.ts), [resolve prepared resources](./examples/resolve-resources.ts), [worker discovery](./examples/worker-discovery.ts), and [signed request to checkout handoff](./examples/request-to-checkout.ts).
+Examples included in the tarball import the built package output: [enroll and publish](./examples/enroll-and-publish.ts), [resolve prepared resources](./examples/resolve-resources.ts), [worker discovery](./examples/worker-discovery.ts), [signed request to checkout handoff](./examples/request-to-checkout.ts), and [protected inspection service](./examples/protected-inspection-service.ts).
 
 MIT licensed. See [LICENSE](./LICENSE).
 
@@ -284,7 +287,7 @@ SDK requests reject HTTP redirects and never retry automatically. An interrupted
 These methods are available from version 0.3.0.
 
 
-## Delivery complaints (unreleased source)
+## Delivery complaints (0.5.0)
 
 `createDeliveryDisputeChallenge(operationId, request)` and `submitDeliveryDisputeAction(operationId, {challengeId, challengeToken, signature})` support buyer complaints, original-recipient responses, buyer closure and private reads. These methods require version 0.5.0 or later.
 
@@ -312,3 +315,37 @@ Dispute writes require `binding` from a fresh signed read. Read challenges conta
 `ProtectedWorkClient` covers all primary protected-work HTTP endpoints with generated OpenAPI types and request/response validation. It requires a pinned contract and verifier hash for job operations, checks signing domains, exact read challenges, transaction targets and approval amounts, and sends no merchant credential. It does not hold keys, sign, broadcast, decode every transaction, verify cryptographic commitments or automatically retry. A configured server may relay signed actions; funding is never relayed.
 
 Start with `new ProtectedWorkClient({baseUrl}).getCapabilities()` and stop when `configured` is false. The isolated Base test does not activate production. SDK helpers have HTTP integration coverage with simulated chain state; the Base test used direct HTTP. Use version 0.5.0 for these helpers. See [the full client guide](https://evidence.contact/merchant-sdk.md#protected-json-work-source-050), [protocol](https://evidence.contact/protected-work.md) and [source examples](examples/protected-work.ts). Replica consent/upload/decision calls remain separate verifier HTTP calls; there are no protected-work CLI, Python wallet or hosted MCP action helpers.
+
+## Fresh-work requests (0.6.0)
+
+Use `createWorkRequestChallenge` / `completeWorkRequest` to publish a buyer-signed public need with acceptance criteria, then `listWorkRequests` / `getWorkRequest` to read it. A merchant client can `proposeWorkRequest` with its declared accepting capability, fee, proposed deadline and seller-funded test budget, or `declineWorkRequest` with a free preflight reason. One current response per merchant is allowed; explicit revisions in 0.7.0 retain all previous versions.
+
+`createWorkRequestSelectionChallenge` / `selectWorkRequestProposal` require the buyer's separate EIP-191 signature. For direct proposals, the SDK validates the returned `workTicketHandoff`, including its exact input fields and the selected format, payout and proposal note. Add the intended buyer wallet and a new persisted grant idempotency key, then follow the existing Work Ticket grant, quote acceptance and payment flow. Selection creates no ticket or payment and does not track either. The deadline and test budget are declarations, not escrow or wallet spending limits. Inputs and responses are public; never include live payment authorizations or secrets.
+
+See [the auditor response example](examples/respond-to-work-request.ts) and [the protocol guide](https://evidence.contact/work-requests.md). Existing wallet/CLI/Python packages do not yet wrap these routes; retain credentials in your runtime and use HTTP/MCP or this SDK.
+
+The grant input is limited to 32 KiB in canonical JSON; an oversized proposal is rejected before it becomes immutable. Compare the actual quote with the retained proposal terms before signing, and check that its deadline is still useful. The copied format/payout/deadline fields are review context, not extra Work Ticket enforcement. Reuse the saved grant key after timeouts; another key can create another ticket. Public demand proves neither buyer funds nor authorization to test an external endpoint. For direct proposals, external test costs remain the seller’s risk, and a free decline does not reimburse them. Explicit protected inspection proposals instead use buyer-funded probes and a separate escrow handoff; see below.
+
+## Protected inspections (0.6.0)
+
+`ProtectedInspectionClient` provides the separate inspection HTTP flow: `getCapabilities`, `prepare`, `prepareFunding` (including the exact task), `getJob`, `createReadChallenge`, `submitObservation`, `start`, candidate submission, replicas, evaluation, result reads and settlement/appeal transaction preparation. Pin the new inspection contract and verifier hash. There is no signing, external HTTP probe, automatic retry or transaction broadcast in this client. The source probe script lives in the service repository. Negative observations may satisfy the narrow paid task; HTTP truth and general audit quality are not certified. Stop on `configured:false`; the separate same-operator pilot is configured, but its full funded lifecycle has not been live-money tested. See https://evidence.contact/protected-inspections.md.
+
+### Offer a protected inspection service
+
+Use the free [service recipe](https://evidence.contact/protected-inspection-service.json) and [seller walkthrough](https://evidence.contact/protected-inspections.md#offer-this-service). Publish the reviewed `payment-readiness-inspection` worker profile, then propose an explicit protected inspection against an actual `/v1/work-requests` record. Profile writes replace existing capabilities. Buyer selection returns `protectedWorkHandoff`; it does not authorize payment. This is not a prepared-artifact offer or Payment Link. Require confirmed escrow and retained buyer evidence before work. SDK 0.6.0 includes `examples/protected-inspection-service.ts`; earlier SDK 0.5.0 can advertise/search profiles but lacks fresh-proposal and inspection helpers. No automatic job inbox or notification is provided.
+
+## Unreleased work agreement helpers
+
+Version 0.7.0 adds `getWorkAgreementTemplate`, `createWorkExecutionReadChallenge`, `readWorkExecution`, `readMerchantWorkExecution` and `listWorkEvents`. npm 0.6.0 does not include these methods. See https://evidence.contact/work-agreements.md for HTTP/MCP equivalents and the opt-in direct-settlement boundary. Persist event cursors with pending ticket references, then reread each current ticket; event receipt is not permission to spend.
+
+## Immutable offer terms (0.7.0)
+
+Version 0.7.0 accepts optional `purchaseDecision` on `createOffer` and exports its type. `getOfferTerms(merchantId, offerId)` reads and validates the immutable terms document and hash. These methods are not included in published 0.6.0. See https://evidence.contact/purchase-decisions.md for limits and compatibility. Neither declaration nor hash certifies the artifact or authorizes payment.
+
+## Merchant sessions (0.7.0)
+
+`createMerchantSession`, `listMerchantSessions` and `revokeMerchantSession` manage optional scoped, expiring service credentials with a parent merchant key. They neither sign payments nor delegate further sessions. These helpers are absent from npm 0.6.0. See https://evidence.contact/runtime-controls.md.
+
+## Fresh-work lifecycle (0.7.0)
+
+`createWorkRequestWithdrawalChallenge` and `withdrawWorkRequest` close open, unselected demand with the buyer EOA signature. To replace terms, publish a new request/key with optional `supersedesRequestId`. `reviseWorkRequestResponse(requestId, responseId, {expectedTermsHash, kind, terms})` appends a version to your owned response; `getWorkResponseHistory` reads all versions. Selection freezes the exact hash. No action cancels a ticket or authorizes payment. These helpers and closed-state validation are included in 0.7.0; 0.6.0 lacks them. See https://evidence.contact/work-request-lifecycle.md.

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { type PurchaseDecision, type OfferTerms } from "./purchase-decisions.js";
+export type { PurchaseDecision, OfferTerms } from "./purchase-decisions.js";
+import type { WorkAgreementTemplate, WorkExecutionRead, WorkEventPage } from "./work-agreements.js";
+export type * from "./work-agreements.js";
 export type EvmAddress = `0x${string}`;
 export type EvmSignature = `0x${string}`;
 export type TransactionHash = `0x${string}`;
@@ -183,6 +187,9 @@ export interface CredentialRotationResult {
     };
 }
 interface MerchantOfferBase {
+    purchaseDecision?: PurchaseDecision;
+    offerTermsHash?: string;
+    offerTermsPath?: string;
     id: string;
     merchantId: string;
     seriesId: string;
@@ -210,6 +217,7 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 interface OfferInputBase {
+    purchaseDecision?: PurchaseDecision;
     title: string;
     description: string;
     priceUSDC: string;
@@ -245,6 +253,9 @@ export interface ArtifactCommitment {
 }
 /** A provider-published, fixed-price resource descriptor. */
 export interface AgentResource {
+    purchaseDecision?: PurchaseDecision;
+    offerTermsHash?: string;
+    offerTermsPath?: string;
     artifact?: ArtifactCommitment;
     share?: string;
     id: string;
@@ -380,6 +391,7 @@ export interface WorkerCapability {
     inputDescription: string;
     resultDescription: string;
     resultContentTypes: ArtifactContentType[];
+    settlementModes?: ("direct_prepayment" | "protected_inspection")[] | undefined;
 }
 /** Full replacement. Discovery flags do not cancel or restrict independently addressed tickets. */
 export interface WorkerProfileInput {
@@ -425,6 +437,127 @@ export interface WorkerDirectoryPage {
     items: WorkerProfileView[];
     nextCursor: number | null;
 }
+export interface FreshWorkRequestInput extends BuyerRequestInput {
+    acceptanceCriteria: string[];
+    supersedesRequestId?: string;
+}
+export interface InspectionPlan {
+    version: "buyer-probe-v1";
+    targetUrl: string;
+    method: "GET";
+    paymentRecipient: EvmAddress;
+    maxTestAmountAtomic: string;
+    maxPaidAttempts: 1;
+}
+export interface FreshWorkProposalInput {
+    capability: string;
+    deliverable: string;
+    priceUSDC: string;
+    deliveryDeadline: string;
+    testPurchaseBudgetUSDC: string;
+    testPurchasePayer: "seller" | "buyer";
+    note: string;
+    settlementMode?: "direct_prepayment" | "protected_inspection";
+    inspection?: InspectionPlan;
+}
+export interface FreshWorkDeclineInput {
+    reason: "endpoint_unavailable" | "unsupported_payment" | "scope_unsupported" | "capacity_unavailable" | "other";
+    note: string;
+}
+export interface PublicFreshWorkRequest extends Omit<FreshWorkRequestInput, "buyer"> {
+    id: string;
+    kind: "fresh";
+    state: "open" | "selected" | "expired" | "withdrawn" | "superseded";
+    closedAt?: string;
+    supersededByRequestId?: string;
+    createdAt: string;
+    expiresAt: string;
+    selectedProposalId: string | null;
+}
+export type FreshWorkResponse = {
+    revision?: number;
+    previousTermsHash?: string;
+    id: string;
+    requestId: string;
+    merchantId: string;
+    payoutAddress: EvmAddress;
+    termsHash: string;
+    createdAt: string;
+} & ({
+    kind: "proposal";
+    terms: FreshWorkProposalInput;
+} | {
+    kind: "decline";
+    terms: FreshWorkDeclineInput;
+});
+export type FreshWorkResponseRevision = {
+    expectedTermsHash: string;
+} & ({
+    kind: "proposal";
+    terms: FreshWorkProposalInput;
+} | {
+    kind: "decline";
+    terms: FreshWorkDeclineInput;
+});
+export interface FreshWorkResponseHistory {
+    requestId: string;
+    responseId: string;
+    versions: FreshWorkResponse[];
+}
+export interface FreshWorkHandoff {
+    kind: "work_ticket_grant";
+    method: "POST";
+    path: "/v1/work-tickets/challenges";
+    body: {
+        merchantId: string;
+        capability: string;
+        input: {
+            workRequestId: string;
+            proposalId: string;
+            proposalTermsHash: string;
+            title: string;
+            contentType: ArtifactContentType;
+            payoutAddress: EvmAddress;
+            proposalNote: string;
+            scope: string;
+            acceptanceCriteria: string[];
+            deliverable: string;
+            deliveryDeadline: string;
+            testPurchaseBudgetUSDC: string;
+            testPurchasePayer: "seller";
+        };
+        maxPriceUSDC: string;
+        expiresInSeconds: number;
+    };
+    buyerWalletRequired: true;
+    grantSignatureRequired: true;
+    paymentAuthorized: false;
+    quoteAcceptanceRequired: true;
+    tracksTicketCreation: false;
+}
+export interface InspectionHandoff {
+    kind: "protected_inspection";
+    path: "/v1/protected-inspections/prepare";
+    task: {
+        version: "funded-inspection-v1";
+        requestId: string;
+        proposalId: string;
+        proposalTermsHash: string;
+        plan: InspectionPlan;
+    };
+    seller: EvmAddress;
+    amountAtomic: string;
+    deliveryDeadline: number;
+    fundingRequired: true;
+    buyerProbeRequired: true;
+    paymentAuthorized: false;
+}
+export interface FreshWorkDetail {
+    request: PublicFreshWorkRequest;
+    responses: FreshWorkResponse[];
+    workTicketHandoff: FreshWorkHandoff | null;
+    protectedWorkHandoff: InspectionHandoff | null;
+}
 export interface BuyerRequestInput {
     buyer: EvmAddress;
     title: string;
@@ -530,6 +663,21 @@ export declare class MerchantApiError extends Error {
  * Minimal, dependency-free HTTP client for 402Mob agent resource resolution and merchant management.
  * It never signs messages, submits wallet transactions, persists API keys, or retries requests.
  */
+export type MerchantSessionScope = "merchant:manage" | "merchant:sales:read" | "merchant:work";
+export interface MerchantSessionInput {
+    name: string;
+    scopes: MerchantSessionScope[];
+    expiresInSeconds: number;
+}
+export interface MerchantSession {
+    id: string;
+    name: string;
+    scopes: MerchantSessionScope[];
+    createdAt: string;
+    expiresAt: string;
+    revokedAt: string | null;
+    lastUsedAt: string | null;
+}
 export declare class MerchantClient {
     #private;
     private readonly baseUrl;
@@ -569,10 +717,20 @@ export declare class MerchantClient {
     getProviderResources(merchantId: string): Promise<AgentProviderCatalog>;
     /** Resolve an older resource ID to its currently published version. This call is public. */
     resolveLatestResource(merchantId: string, offerId: string): Promise<ResolvedAgentResource>;
+    /** Read immutable public decision terms, including for an unpublished exact offer. Verifies the origin-backed SHA-256; not a seller signature. */
+    getOfferTerms(merchantId: string, offerId: string): Promise<OfferTerms>;
     setDiscoverable(discoverable: boolean): Promise<{
         merchantId: string;
         discoverable: boolean;
     }>;
+    createMerchantSession(input: MerchantSessionInput): Promise<{
+        session: MerchantSession;
+        token: string;
+    }>;
+    listMerchantSessions(): Promise<{
+        items: MerchantSession[];
+    }>;
+    revokeMerchantSession(sessionId: string): Promise<MerchantSession>;
     createOffer(input: CreateOfferInput): Promise<MerchantOffer>;
     setOfferActive(offerId: string, active: boolean): Promise<MerchantOffer>;
     listSales(limit?: number): Promise<SaleList>;
@@ -606,7 +764,76 @@ export declare class MerchantClient {
         buyerResultChallenge: string;
         retentionDays: number;
     }>;
+    /** New source API: opt-in linkage; selection still creates neither a ticket nor a payment. */
+    getWorkAgreementTemplate(requestId: string): Promise<WorkAgreementTemplate>;
+    createWorkExecutionReadChallenge(requestId: string, buyer: EvmAddress): Promise<{
+        challengeId: string;
+        message: string;
+        expiresAt: string;
+    }>;
+    readWorkExecution(requestId: string, proof: {
+        challengeId: string;
+        signature: EvmSignature;
+    }): Promise<WorkExecutionRead>;
+    readMerchantWorkExecution(requestId: string): Promise<WorkExecutionRead>;
+    listWorkEvents(input?: {
+        after?: number;
+        limit?: number;
+    }): Promise<WorkEventPage>;
     /** Free public demand. Caller persists the key, signs the returned message and completes separately. */
+    createWorkRequestChallenge(input: FreshWorkRequestInput, idempotencyKey: string): Promise<BuyerRequestChallenge>;
+    completeWorkRequest(input: FreshWorkRequestInput & {
+        challengeId: string;
+        signature: EvmSignature;
+    }, idempotencyKey: string): Promise<FreshWorkDetail & {
+        replay: boolean;
+    }>;
+    listWorkRequests(input?: ResolveAgentResourcesInput): Promise<{
+        items: PublicFreshWorkRequest[];
+        nextCursor: number | null;
+    }>;
+    getWorkRequest(id: string): Promise<FreshWorkDetail>;
+    proposeWorkRequest(id: string, input: FreshWorkProposalInput): Promise<{
+        response: FreshWorkResponse;
+        replay: boolean;
+    }>;
+    declineWorkRequest(id: string, input: FreshWorkDeclineInput): Promise<{
+        response: FreshWorkResponse;
+        replay: boolean;
+    }>;
+    createWorkRequestWithdrawalChallenge(id: string, input: {
+        buyer: EvmAddress;
+    }): Promise<{
+        challengeId: string;
+        message: string;
+        expiresAt: string;
+    }>;
+    withdrawWorkRequest(id: string, input: {
+        challengeId: string;
+        signature: EvmSignature;
+    }): Promise<FreshWorkDetail & {
+        replay: boolean;
+    }>;
+    reviseWorkRequestResponse(id: string, responseId: string, input: FreshWorkResponseRevision): Promise<{
+        response: FreshWorkResponse;
+        replay: boolean;
+    }>;
+    getWorkResponseHistory(id: string, responseId: string): Promise<FreshWorkResponseHistory>;
+    createWorkRequestSelectionChallenge(id: string, input: {
+        buyer: EvmAddress;
+        proposalId: string;
+    }): Promise<{
+        challengeId: string;
+        message: string;
+        expiresAt: string;
+        proposal: FreshWorkResponse;
+    }>;
+    selectWorkRequestProposal(id: string, input: {
+        challengeId: string;
+        signature: EvmSignature;
+    }): Promise<FreshWorkDetail & {
+        replay: boolean;
+    }>;
     createBuyerRequestChallenge(input: BuyerRequestInput, idempotencyKey: string): Promise<BuyerRequestChallenge>;
     completeBuyerRequest(input: BuyerRequestInput & {
         challengeId: string;
@@ -655,3 +882,6 @@ export declare class MerchantClient {
 export { ProtectedWorkClient, ProtectedWorkApiError } from "./protected-work.js";
 export type { ProtectedWorkClientOptions } from "./protected-work.js";
 export type * from "./protected-work-types.js";
+export { ProtectedInspectionClient, ProtectedInspectionApiError } from "./protected-inspection.js";
+export type * from "./protected-inspection-types.js";
+export type { ProtectedInspectionClientOptions } from "./protected-inspection.js";