@crawlcheck/sdk 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @crawlcheck/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for the CrawlCheck API and the offline verifier for its evidence, in one package with no dependencies.
+
+```sh
+npm i @crawlcheck/sdk
+```
+
+## Read a record
+
+```js
+import { CrawlCheck } from "@crawlcheck/sdk";
+const cc = new CrawlCheck();                       // { key: "cc_…" } for licence-gated fields
+const mr = await cc.machineRecord({ domain: "example.com" });
+mr.findings;            // gated exactly like the website: the top finding without a licence
+mr.score_ledger;        // what each row and finding does to the grade
+```
+
+Every request and response type is generated from https://crawlcheck.io/openapi.json. Any documented route is callable with types checked against the contract:
+
+```ts
+await cc.get("/api/explain", { domain: "example.com", code: "NO_LLMS_TXT" });
+await cc.get("/api/explain", { website: "x" });   // compile error: not a parameter of this operation
+```
+
+## Do not trust the API: check the evidence yourself
+
+```js
+const v = await cc.verifyOffline(mr.subject.report_id);   // downloads the bundle, verifies it HERE
+v.checks;   // manifest hash, Ed25519 signature, key id, record digest, Merkle path to the day's root,
+            // OpenTimestamps proof (Bitcoin), sealed roots over fetches, decisions and facts
+```
+
+`ok: true` passed, `ok: false` failed, `ok: null` could not run and `why` says why. A null is never a pass.
+
+Remediation receipts (before, declared fix, deployment, after, verdict, signed):
+
+```js
+import { verifyReceipt } from "@crawlcheck/sdk";
+const rc = await cc.receipt("rc1:…");
+const r = await verifyReceipt(rc);                                  // hash, key id, signature, order
+const ours = (await cc.publishedKeyIds()).includes(rc.signature.kid);  // the one check offline cannot do
+const accept = r.verified && ours;
+```
+
+## Prove the verifier
+
+```js
+const suite = await cc.conformance();   // 19 real bundles and receipts, valid and tampered, with expected outputs
+suite.ok;                              // every fixture gave exactly its expected checks and verdict
+```
+
+`npm test` in the installed package runs the conformance suite and live checks against crawlcheck.io.
+
+## Errors
+
+A refused request throws `CrawlCheckError` with `status`, `body` and `locked` (true for "this needs a licence for the domain").
+
+Requires Node 20+ or any current browser (WebCrypto Ed25519).