@spoolis/accept

Accept work with Spoolis

@spoolis/accept turns your acceptance policy and delivered work into a verified Spoolis Outcome. It is a small, dependency-free client for the canonical agreement, judgment, and Outcome path.

Install

npm install @spoolis/accept

Node 20 or later is required.

Make one call

import * as spoolis from '@spoolis/accept'

const criteria = 'Every row must have status done'
const evidence = { rows: [{ id: 1, status: 'done' }] }
const judge = {
  meta: {
    evaluator_id: 'my-evaluator',
    kind: 'buyer_owned',
    evaluator_version: '1',
    proof_requirement: 'declared',
  },
  async run({ evidence }) {
    return { pass: evidence.rows.every((row) => row.status === 'done') }
  },
}

const outcome = await spoolis.accept({ criteria, evidence, judge }, {
  baseUrl: 'https://spoolis.com',
  apiKey: process.env.SPOOLIS_API_KEY,
})

console.log(outcome.status, outcome.receiptId)

Use policy when you need pricing, thresholds, or uncertainty behavior:

import * as spoolis from '@spoolis/accept'

const outcome = await spoolis.accept({
  policy: {
    criteria: [{
      description: 'Every row includes status',
      check: { checker: 'completeness', required_fields: ['status'] },
    }],
    units: 100,
    unitValueCents: 500,
  },
  evidence: { rows },
}, {
  baseUrl: 'https://spoolis.com',
  apiKey: process.env.SPOOLIS_API_KEY,
})

console.log(outcome)
// {
//   status: 'partial',
//   accepted: 82,
//   rejected: 18,
//   uncertain: 0,
//   earnedCents: 41000,
//   spoolId: 'spl_example',
//   receiptId: 'ocr_example',
//   receiptUrl: 'https://spoolis.com/r/ocr_example',
//   receipt: { id: 'ocr_example', result: 'partial', amounts: { earned_cents: 41000 } }
// }

The API response uses earned_cents. The SDK exposes the same server-authored value as earnedCents; it does not recompute economics.

Define a policy

An AcceptancePolicy has these fields:

• criteria: A nonempty description or 1–50 descriptions paired with deterministic checks.
• units and unitValueCents: Optional positive integers that must appear together. Their product is the maximum amount unless you also provide the same value as maxAmountCents.
• maxAmountCents: An optional positive integer cap.
• acceptIf: Optional quality and consensus thresholds from 0–100. These are for an external scored judge.
• onUncertain: Optional and currently limited to hold.

Evidence must provide exactly one of rows, payload, or url. Every call requires exactly one of top-level criteria or policy. The criteria shorthand is equivalent to policy: { criteria }; use policy for all other policy fields.

Bring your own judge

Use your own evaluator without computing agreement or evidence hashes, as shown in the first example.

For per-unit evaluation, add units and unitValueCents in policy, then return { units: [{ id, pass }] }. Spoolis passes the exact unitIds to judge.run. For scored evaluation, set acceptIf and meta.schemaId, then return either { quality, consensus } or scored units. acceptWithJudge exposes the same lifecycle directly and accepts either { criteria, evidence, judge } or { policy, evidence, judge }.

The helper creates a unilateral Spool, submits evidence, reads the server-authored binding, runs your evaluator, submits its normalized result, verifies the Spool, and returns the same AcceptOutcome shape as accept. Server binding checks remain mandatory.

Fail safely

An uncertain result never becomes accepted. Missing fields, contradictory counts and receipt status, unknown receipt status, or any nonzero uncertain count map to status: 'uncertain'. Rejected and uncertain units do not become earned value. The SDK preserves the server's earned_cents value and does not author a replacement.

Verify the receipt

Use @spoolis/receipt-verifier to verify the signed Outcome Receipt offline before a consequential next action.

Exports

The package exports accept, acceptWithJudge, acceptancePolicySchema, AcceptancePolicyError, ExternalJudgeLifecycleError, JudgeAdapterError, toOneShotBody, deterministicChecker, scoredJudge, binaryJudge, toExternalJudgeDeclaration, and version. TypeScript users also receive AcceptancePolicy and the related input, outcome, judge, and check types.