teppi-check 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# teppi-check
+
+Send one unpaid request to any paid endpoint and see what it actually advertises.
+
+```bash
+npx teppi-check https://some-seller.example/v1/extract
+```
+
+No install and no dependencies: the published package is a single bundled file, so the validator
+that reads a schema here is the same build that read it when the record was written.
+
+It sends the request the scheduled prober sends. Both call one `handshake` function, and a test
+runs the two side by side and fails if the bytes on the wire differ. That is what makes an entry
+in the record something you can check rather than something you are asked to accept.
+
+```
+  POST https://some-seller.example/v1/extract
+  2026-08-30T10:22:14.263Z
+
+  402 in 118ms
+  endpoint answered                                   ok
+  asks for payment                                    ok
+  payment terms parse                                 ok
+     read from the body
+  offers at least one way to pay                      ok
+     1 option(s)
+  price is stated                                     ok
+  network is stated                                   ok
+  scheme is stated                                    ok
+  payout address is stated                            ok
+  asset is stated                                     ok
+  input schema is usable                              ok
+  output schema is usable                             fail
+     not declared, so no response can ever be checked against it
+  payment terms are not cached                        fail
+     no cache-control, so a proxy may serve stale terms
+
+  advertised
+     10000 0x2222...2222 on eip155:8453 via exact
+
+  request  sha256:ba6f7ff0...0878
+  response sha256:0a83a213...2496
+
+  2 checks failed
+```
+
+## Why this exists
+
+Teppi keeps the Machine Delivery Record: what happened when someone paid a machine service and
+waited for something back. A record is only worth reading if a stranger can check it, so the
+probe that produces it ships as a command anyone can run. Point it at an endpoint, compare the
+output to the published entry, and decide for yourself.
+
+This is the unpaid half of the probe. It reports what an endpoint promises. Whether it delivers
+takes a purchase, which the full prober does on a schedule.
+
+## What it checks
+
+| Check | Fails when |
+|---|---|
+| endpoint answered | connection refused, DNS failure, or timeout |
+| asks for payment | anything other than a 402 |
+| payment terms parse | no readable terms in the `payment-required` header or the body |
+| offers at least one way to pay | `accepts` is missing or empty |
+| price, network, scheme, payout address, asset | any entry in `accepts` leaves one unstated |
+| input schema is usable | absent, or present but not a compilable JSON Schema |
+| output schema is usable | same. Without one, no response can ever be validated |
+| payment terms are not cached | no `no-store` or `no-cache`, so a proxy may serve stale terms and stale nonces |
+
+Terms are read from the `payment-required` header (base64 or plain JSON) or from the response
+body, because deployed servers use both.
+
+## Options
+
+```
+  --method <verb>      default POST
+  --body <json|@file>  default {}
+  --json               machine readable output
+  --timeout <ms>       default 15000
+  --user-agent <ua>    default node
+```
+
+Exit codes: `0` every check passed, `1` a check failed, `2` the endpoint could not be reached.
+
+Requests go over HTTPS only, apart from localhost.
+
+## Use it in CI
+
+```yaml
+- run: npx teppi-check https://your-api.example/v1/thing
+```
+
+The command fails the build when your own endpoint stops advertising what it should, which is
+the failure mode nobody notices until buyers quietly stop calling.
+
+## Library
+
+```ts
+import { probe } from 'teppi-check';
+
+const result = await probe({ url: 'https://some-seller.example/v1/extract' });
+console.log(result.verdict, result.checks);
+```
+
+MIT.

package/npm/checks.d.ts

@@ -0,0 +1,20 @@
+import { type PaymentTerms } from './terms.js';
+export type CheckStatus = 'pass' | 'fail' | 'skip';
+export type Check = {
+    readonly id: string;
+    readonly label: string;
+    readonly status: CheckStatus;
+    readonly detail?: string;
+};
+export declare function schemaCheck(id: string, label: string, schema: unknown): Check;
+export type HandshakeInput = {
+    readonly status: number;
+    readonly headers: Headers;
+    readonly terms: PaymentTerms | null;
+    readonly parseError: string | null;
+    readonly source: string;
+};
+export declare function runHandshakeChecks(input: HandshakeInput): Check[];
+export declare function unreachable(reason: string): Check[];
+export declare function verdictOf(checks: readonly Check[]): 'pass' | 'fail';
+//# sourceMappingURL=checks.d.ts.map

package/npm/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../src/checks.ts"],"names":[],"mappings":"AAEA,OAAO,EAA2B,KAAK,YAAY,EAAsB,MAAM,mBAAmB,CAAC;AAGnG,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEnD,MAAM,MAAM,KAAK,GAAG;IACnB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAqBF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,KAAK,CAa7E;AAED,MAAM,MAAM,cAAc,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACxB,CAAC;AA+BF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,KAAK,EAAE,CA4CjE;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,CAEnD;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,GAAG,MAAM,CAEnE"}

package/npm/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/npm/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}