402mob-merchant-sdk 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,29 @@
 # Changelog
 
-## 0.4.2 — prepared, unpublished
+## 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.
+
+- Require an authenticated-read binding for dispute writes. Reject unexpected signing origins/consent, contradictory payment and delivery states, and immutable binding drift across evidence events. Challenge issuance reveals no operation or case state.
+
+- Require stateless dispute challenge tokens; distinguish write acknowledgments from authenticated evidence reads. Validate operation, statement, binding and lifecycle consistency; preserve settlement status and post-closure seller evidence.
+
+- Add wallet-signed delivery complaint, seller response, buyer closure and evidence-read methods and types. No automatic payment or refund.
+
+## 0.4.2 — published
 
 - Add optional `artifact` commitment and `share` fields to resolved resources. Validate supplied commitments and preserve compatibility with older servers that omit them.
 

package/README.md

@@ -1,6 +1,9 @@
 # 402Mob Merchant SDK
 
-Source 0.4.2 is prepared locally with optional Payment Links commitment/share types and validation. Published 0.4.1 remains unchanged; these additions require the new source build until publication.
+**Version 0.6.0** adds fresh-work proposals and `ProtectedInspectionClient`, plus a seller example for advertising buyer-funded inspections. Use `402mob-merchant-sdk@0.6.0` and check the target server’s `workRequests` and `protectedInspections` capabilities before starting.
+
+
+Version 0.5.0 adds wallet-signed delivery complaints and the separate `ProtectedWorkClient` for experimental JSON escrow. Install `402mob-merchant-sdk@0.6.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).
 
@@ -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).
 
@@ -282,3 +285,51 @@ The supported states are `open`, `claimed`, `quoted`, `accepted`, `paying`, `pai
 SDK requests reject HTTP redirects and never retry automatically. An interrupted mutation may have completed. Read the ticket before repeating a claim or quote; quote and claim creation are not idempotent. Repeating identical result content is supported while retained. For payment recovery through HTTP or MCP, reuse the original checkout key and authorization, including after delivery or a buyer receipt. The SDK does not submit payments.
 
 These methods are available from version 0.3.0.
+
+
+## Delivery complaints (unreleased source)
+
+`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.
+
+```ts
+const challenge = await client.createDeliveryDisputeChallenge(operationId, {
+  wallet: account.address, action: "read"
+});
+const signature = await account.signMessage({ message: challenge.message });
+const response = await client.submitDeliveryDisputeAction(operationId, {
+  challengeId: challenge.challengeId, challengeToken: challenge.challengeToken, signature
+});
+if (response.kind === "evidence") {
+  // Inspect response.dispute and response.payment.
+}
+```
+
+No API key or payment is sent. Sign with the original payer or recipient wallet; keep proofs private. Retry exact signed writes after interruption; reads need fresh challenges. This records statements, not arbitration or refunds. See [the complete workflow](https://evidence.contact/delivery-disputes.md).
+
+Dispute writes (including retries) return `kind: "acknowledgment"` and the original action receipt only. Fresh wallet-signed reads return `kind: "evidence"` with the current case. Return the opaque `challengeToken` unchanged; it is required for submission. Buyer closure preserves the seller’s right to append evidence. Settlement status is independent of operation/result expiry. SDK checks enforce structural and lifecycle consistency, not cryptographic verification of exported signatures.
+
+Dispute writes require `binding` from a fresh signed read. Read challenges contain no private operation data and do not confirm that an operation or case exists. Check the returned origin and consent text before signing; `dispute_binding_conflict` requires a new read and signed statement. The SDK rejects origin/consent changes, contradictory delivery/payment states and inconsistent immutable bindings across events.
+
+## Protected work (0.5.0)
+
+`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 immutable response per merchant is allowed.
+
+`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.

package/dist/index.d.ts

@@ -4,6 +4,119 @@ export type TransactionHash = `0x${string}`;
 export type ProofMethod = "approve_zero" | "transfer_zero";
 export type ArtifactContentType = "application/json" | "text/plain; charset=utf-8";
 export type WorkTicketState = "open" | "claimed" | "quoted" | "accepted" | "paying" | "paid" | "delivered" | "accepted_by_buyer" | "disputed" | "expired";
+export interface DeliveryDisputeBinding {
+    payer: EvmAddress;
+    recipient: EvmAddress;
+    requestHash: string;
+    workTicketId: string | null;
+    quoteTermsHash: string | null;
+    resultHashAtOpen: string | null;
+    transaction: string | null;
+    amountAtomic: string;
+    asset: EvmAddress;
+    network: "eip155:8453";
+}
+export type DeliveryDisputeRequest = {
+    wallet: EvmAddress;
+    action: "open";
+    expectedRevision: 0;
+    binding: DeliveryDisputeBinding;
+    reason: "not_delivered" | "unreadable" | "terms_mismatch";
+    detail: string;
+    evidenceHashes: string[];
+} | {
+    wallet: EvmAddress;
+    action: "respond";
+    expectedRevision: number;
+    binding: DeliveryDisputeBinding;
+    detail: string;
+    evidenceHashes: string[];
+} | {
+    wallet: EvmAddress;
+    action: "close";
+    expectedRevision: number;
+    binding: DeliveryDisputeBinding;
+    outcome: "resolved" | "unresolved";
+    detail: string;
+    evidenceHashes: string[];
+} | {
+    wallet: EvmAddress;
+    action: "read";
+};
+export interface DeliveryDisputeChallenge {
+    challengeToken: string;
+    challengeId: string;
+    message: string;
+    expiresAt: string;
+    submit: string;
+}
+export interface DeliveryDisputeEvent {
+    revision: number;
+    action: "open" | "respond" | "close";
+    wallet: string;
+    createdAt: string;
+    statement: Exclude<DeliveryDisputeRequest, {
+        action: "read";
+    }>;
+    message: string;
+    signature: string;
+    challengeId: string;
+}
+export interface DeliveryDisputeEvidence {
+    protocol: "402mob.delivery-dispute.v1";
+    kind: "evidence";
+    operationId: string;
+    operationState: string;
+    binding: DeliveryDisputeBinding;
+    dispute: null | {
+        operationId: string;
+        buyer: string;
+        seller: string;
+        status: "open" | "responded" | "closed";
+        outcome: "resolved" | "unresolved" | null;
+        revision: number;
+        openedAt: string;
+        expiresAt: string;
+        responseDueAt: string;
+        buyerReviewDueAt: string | null;
+        binding: {
+            requestHash: string;
+            workTicketId: string | null;
+            quoteTermsHash: string | null;
+            resultHashAtOpen: string | null;
+            transaction: string | null;
+            amountAtomic: string;
+            asset: string;
+            network: string;
+        };
+        events: DeliveryDisputeEvent[];
+    };
+    payment: {
+        state: "settled" | "pending" | "failed" | "unconfirmed";
+        transaction: string | null;
+    };
+    delivery: {
+        resultHash: string | null;
+        resultAvailable: boolean;
+    };
+    responseOverdue: boolean;
+    buyerReviewOverdue: boolean;
+    scope: string;
+    replay: boolean;
+}
+export interface DeliveryDisputeAcknowledgment {
+    protocol: "402mob.delivery-dispute.v1";
+    kind: "acknowledgment";
+    operationId: string;
+    receipt: {
+        challengeId: string;
+        action: "open" | "respond" | "close";
+        revision: number;
+        createdAt: string;
+    };
+    replay: boolean;
+}
+export type DeliveryDisputeResponse = DeliveryDisputeEvidence | DeliveryDisputeAcknowledgment;
 export interface EnrollmentChallenge {
     challengeId: string;
     message: string;
@@ -312,6 +425,108 @@ export interface WorkerDirectoryPage {
     items: WorkerProfileView[];
     nextCursor: number | null;
 }
+export interface FreshWorkRequestInput extends BuyerRequestInput {
+    acceptanceCriteria: 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?: "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";
+    createdAt: string;
+    expiresAt: string;
+    selectedProposalId: string | null;
+}
+export type FreshWorkResponse = {
+    id: string;
+    requestId: string;
+    merchantId: string;
+    payoutAddress: EvmAddress;
+    termsHash: string;
+    createdAt: string;
+} & ({
+    kind: "proposal";
+    terms: FreshWorkProposalInput;
+} | {
+    kind: "decline";
+    terms: FreshWorkDeclineInput;
+});
+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;
@@ -494,6 +709,41 @@ export declare class MerchantClient {
         retentionDays: number;
     }>;
     /** 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;
+    }>;
+    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;
@@ -529,6 +779,19 @@ export declare class MerchantClient {
     }): Promise<BuyerRequestDetail & {
         replay: boolean;
     }>;
+    /** Free, wallet-signed complaint/response/closure/read. No bearer key or payment is sent. */
+    createDeliveryDisputeChallenge(operationId: string, input: DeliveryDisputeRequest): Promise<DeliveryDisputeChallenge>;
+    /** Retry the same signed write after interruption; private reads require a fresh challenge. */
+    submitDeliveryDisputeAction(operationId: string, input: {
+        challengeId: string;
+        challengeToken: string;
+        signature: EvmSignature;
+    }): Promise<DeliveryDisputeResponse>;
     private request;
 }
-export {};
+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";