@skeinlabs/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# @skeinlabs/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.
+TypeScript client for [Skein](https://skeinlabs.site): one call returns a
+listing verdict for an EVM token (**APPROVE**, **REJECT**, **ESCALATE** or
+**ABSTAIN**), with reasons, open risks, cost and a hash anyone can recompute.
+
+- `verdict()`, `quote()`, `verify()`, `stream()`, `bom()`, `submit()` / `wait()`
+- typed errors (`SkeinError`, `SpendCapError`) carrying the API's codes
+- retries that reuse the idempotency key, so a retried call is never charged twice
+- a per-call spend cap, checked **before** any payment
+- two ways to pay: a Skein partner key, or per call through Telegraph escrow
+- every verdict signed by Skein, checkable offline with `@skeinlabs/sdk/attest`
+- no runtime dependencies (the Telegraph and attest entries need `viem`)
+
+**[Read the full tutorial →](https://skeinlabs.site/tutorial)**
+
+## Install
+
+```sh
+npm install @skeinlabs/sdk
+# for the Telegraph rail, also:
+npm install viem
+```
+
+Node 20 or later, or any runtime with `fetch` (Bun, Deno, edge workers, browsers).
+
+## Quote (free, no key)
+
+```ts
+import { Skein } from "@skeinlabs/sdk";
+
+const skein = new Skein({ apiUrl: "https://api.skeinlabs.site" });
+const q = await skein.quote({ subject: { chainId: 8453, token: "0x4200000000000000000000000000000000000006" } });
+console.log(q.priceUsdc, q.checks?.map((c) => c.check));
+```
+
+## Verdict (partner key)
+
+```ts
+import { Skein, SkeinError, SpendCapError } from "@skeinlabs/sdk";
+
+const skein = new Skein({
+  apiUrl: "https://api.skeinlabs.site",
+  payer: { kind: "apiKey", key: process.env.SKEIN_API_KEY! },
+  maxUsdcPerCall: 0.3, // refused before paying above this
+});
+
+try {
+  const v = await skein.verdict({
+    subject: { chainId: 8453, token: "0x…" },
+    policy: "dex-list@0.2.0",
+    context: { socialHandle: "project_handle", repoUrl: "https://github.com/org/repo" }, // optional: buys bot and code checks
+    onEvent: (e) => console.log(e.type), // plan, purchase, finding, decision, done
+  });
+  if (v.verdict !== "APPROVE") console.log("needs a human:", v.reasons.map((r) => r.detail));
+  const report = await skein.verify(v.id); // recompute it from the raw paid answers
+  console.log(report.ok ? "verified" : report.problems);
+} catch (e) {
+  if (e instanceof SpendCapError) console.log(`quoted ${e.priceUsdc} USDC, cap ${e.capUsdc}`);
+  else if (e instanceof SkeinError) console.log(e.code, e.message);
+  else throw e;
+}
+```
+
+## Verdict (pay per call through Telegraph)
+
+No Skein account: each verdict is one paid Telegraph ask, settled from your
+own escrow on the Telegraph network.
+
+```ts
+import { Skein } from "@skeinlabs/sdk";
+import { TelegraphClient, TESTNET, viemSigner } from "@skeinlabs/sdk/telegraph";
+
+const client = new TelegraphClient({
+  network: TESTNET, // Sepolia escrow
+  signer: viemSigner(process.env.PAYER_KEY as `0x${string}`), // a burner, never a treasury key
+  maxUusdcPerCall: 300_000, // 0.30 USDC: no 402 challenge is signed above this
+});
+const skein = new Skein({ apiUrl: "https://api.skeinlabs.site", payer: { kind: "telegraph", client } });
+const v = await skein.verdict({ subject: { chainId: 1, token: "0x…" } });
+console.log(v.verdict, v.payment); // { rail: "telegraph", minerId, amountUsdc, receiptHash, signalHash }
+```
+
+## Check Skein's signature yourself
+
+Every verdict is signed by Skein (EIP-191) over its id, subject, outcome,
+policy, verdict hash, receipts root and cost. The signer's address is published
+at `https://api.skeinlabs.site/v1/status` (`attester`). The check rebuilds the
+message from the verdict's own fields, so an edited verdict fails even with the
+original signature attached:
+
+```ts
+import { verifyAttestation } from "@skeinlabs/sdk/attest";   // needs viem
+
+const { attester } = await (await fetch("https://api.skeinlabs.site/v1/status")).json();
+const check = await verifyAttestation(v, { signer: attester });
+if (!check.ok) throw new Error(check.problems.join("; "));
+```
+
+Pin the attester address in your own config rather than fetching it on every call.
+
+## API
+
+| Method | Cost | What it does |
+|---|---|---|
+| `quote({ subject, policy? })` | free | What a verdict would buy and cost, or why it would be refused |
+| `verdict(req)` | paid | Buys one verdict and resolves once it is sealed |
+| `submit(req)` / `wait(id)` | paid | The same in two steps, for queues and long-running jobs |
+| `get(id)` | free | A stored verdict, or `{ status: "running" }` |
+| `stream(id)` | free | The verdict's live events as an async iterator |
+| `bom(id)` | free | The bill of materials: every paid input and its receipt |
+| `verify(id)` | free | Recomputes the verdict hash and the receipts' Merkle root |
+
+Options: `apiUrl`, `payer`, `maxUsdcPerCall`, `retries` (2), `maxRetryWaitMs`
+(10 s), `requestTimeoutMs` (15 s), `timeoutMs` (120 s), `fetch`.
+
+Verdicts are risk evidence, not investment advice. Treat anything but
+`APPROVE` as "do not proceed without a human".
+
+## License
+
+Apache-2.0

package/dist/attest.d.ts

@@ -0,0 +1,51 @@
+import { A as Attestation } from './types-B_RIoOCq.js';
+
+/**
+ * The message Skein signs for every verdict (EIP-191 personal_sign, the same
+ * scheme Telegraph uses for escrow payments). It names everything a reader
+ * relies on (the subject, the outcome, the policy and engine, the verdict hash
+ * and the receipts' Merkle root, the cost) in plain lines, so a signature can
+ * travel with a listing memo or a payment and be checked by anyone who knows
+ * Skein's published attester address. Nothing secret, no dependencies: the API
+ * signs it and @skeinlabs/sdk/attest rebuilds it to verify.
+ */
+interface AttestedVerdict {
+    id: string;
+    subject: {
+        chainId: number;
+        token: string;
+    };
+    verdict: string;
+    riskBps: number;
+    confidenceBps: number;
+    policy: {
+        id: string;
+        version: string;
+    };
+    engineVersion: string;
+    verdictHash: string;
+    bom: {
+        root: string;
+    };
+    cost: {
+        priceUsdc: number;
+        upstreamUsdc: number;
+    };
+    network: string;
+    createdAt: string;
+}
+declare function attestationMessage(v: AttestedVerdict): string;
+
+interface AttestationCheck {
+    ok: boolean;
+    /** Who signed it, as the verdict claims. */
+    signer: string | null;
+    problems: string[];
+}
+declare function verifyAttestation(v: AttestedVerdict & {
+    attestation?: Attestation | null;
+}, opts: {
+    signer: string;
+}): Promise<AttestationCheck>;
+
+export { type AttestationCheck, type AttestedVerdict, attestationMessage, verifyAttestation };

package/dist/attest.js

@@ -0,0 +1,47 @@
+// src/attest.ts
+import { verifyMessage } from "viem";
+
+// ../engine/src/attest.ts
+var ATTESTATION_TITLE = "Skein verdict attestation v1";
+function attestationMessage(v) {
+  return [
+    ATTESTATION_TITLE,
+    `id: ${v.id}`,
+    `subject: eip155:${v.subject.chainId}:${v.subject.token.toLowerCase()}`,
+    `verdict: ${v.verdict}`,
+    `risk_bps: ${v.riskBps}`,
+    `confidence_bps: ${v.confidenceBps}`,
+    `policy: ${v.policy.id}@${v.policy.version}`,
+    `engine: ${v.engineVersion}`,
+    `verdict_hash: ${v.verdictHash}`,
+    `bom_root: ${v.bom.root}`,
+    `price_usdc: ${v.cost.priceUsdc}`,
+    `upstream_usdc: ${v.cost.upstreamUsdc}`,
+    `network: ${v.network}`,
+    `created_at: ${v.createdAt}`
+  ].join("\n");
+}
+
+// src/attest.ts
+async function verifyAttestation(v, opts) {
+  const a = v.attestation;
+  if (!a) return { ok: false, signer: null, problems: ["the verdict carries no attestation (the API has no attestation key set)"] };
+  const problems = [];
+  if (a.scheme !== "eip191") problems.push(`unknown scheme ${a.scheme}`);
+  if (a.signer.toLowerCase() !== opts.signer.toLowerCase()) problems.push(`signed by ${a.signer}, not the expected ${opts.signer}`);
+  const rebuilt = attestationMessage(v);
+  if (rebuilt !== a.message) problems.push("the signed message does not match the verdict's fields");
+  let valid = false;
+  try {
+    valid = await verifyMessage({ address: opts.signer, message: rebuilt, signature: a.signature });
+  } catch {
+    valid = false;
+  }
+  if (!valid) problems.push("the signature does not recover to the expected signer for this verdict");
+  return { ok: problems.length === 0, signer: a.signer, problems };
+}
+export {
+  attestationMessage,
+  verifyAttestation
+};
+//# sourceMappingURL=attest.js.map

package/dist/attest.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/attest.ts","../../engine/src/attest.ts"],"sourcesContent":["/**\n * Check a Skein verdict's signature yourself (needs viem). Import from\n * \"@skeinlabs/sdk/attest\".\n *\n *   import { verifyAttestation } from \"@skeinlabs/sdk/attest\";\n *   const r = await verifyAttestation(v, { signer: SKEIN_ATTESTER });   // the address at /v1/status\n *   if (!r.ok) throw new Error(r.problems.join(\"; \"));\n *\n * It rebuilds the signed message from the verdict's own fields, so a verdict\n * whose outcome, hash, cost or subject was edited after signing fails, even\n * when the attached message and signature are left untouched.\n */\nimport { verifyMessage } from \"viem\";\nimport { attestationMessage, type AttestedVerdict } from \"@skein/engine/attest\";\nimport type { Attestation } from \"./types\";\n\nexport { attestationMessage, type AttestedVerdict };\n\nexport interface AttestationCheck {\n  ok: boolean;\n  /** Who signed it, as the verdict claims. */\n  signer: string | null;\n  problems: string[];\n}\n\nexport async function verifyAttestation(v: AttestedVerdict & { attestation?: Attestation | null }, opts: { signer: string }): Promise<AttestationCheck> {\n  const a = v.attestation;\n  if (!a) return { ok: false, signer: null, problems: [\"the verdict carries no attestation (the API has no attestation key set)\"] };\n  const problems: string[] = [];\n  if (a.scheme !== \"eip191\") problems.push(`unknown scheme ${a.scheme}`);\n  if (a.signer.toLowerCase() !== opts.signer.toLowerCase()) problems.push(`signed by ${a.signer}, not the expected ${opts.signer}`);\n  const rebuilt = attestationMessage(v);\n  if (rebuilt !== a.message) problems.push(\"the signed message does not match the verdict's fields\");\n  let valid = false;\n  try {\n    valid = await verifyMessage({ address: opts.signer as `0x${string}`, message: rebuilt, signature: a.signature as `0x${string}` });\n  } catch {\n    valid = false;\n  }\n  if (!valid) problems.push(\"the signature does not recover to the expected signer for this verdict\");\n  return { ok: problems.length === 0, signer: a.signer, problems };\n}\n","/**\n * The message Skein signs for every verdict (EIP-191 personal_sign, the same\n * scheme Telegraph uses for escrow payments). It names everything a reader\n * relies on (the subject, the outcome, the policy and engine, the verdict hash\n * and the receipts' Merkle root, the cost) in plain lines, so a signature can\n * travel with a listing memo or a payment and be checked by anyone who knows\n * Skein's published attester address. Nothing secret, no dependencies: the API\n * signs it and @skeinlabs/sdk/attest rebuilds it to verify.\n */\nexport interface AttestedVerdict {\n  id: string;\n  subject: { chainId: number; token: string };\n  verdict: string;\n  riskBps: number;\n  confidenceBps: number;\n  policy: { id: string; version: string };\n  engineVersion: string;\n  verdictHash: string;\n  bom: { root: string };\n  cost: { priceUsdc: number; upstreamUsdc: number };\n  network: string;\n  createdAt: string;\n}\n\nexport const ATTESTATION_SCHEME = \"eip191\";\nexport const ATTESTATION_TITLE = \"Skein verdict attestation v1\";\n\nexport function attestationMessage(v: AttestedVerdict): string {\n  return [\n    ATTESTATION_TITLE,\n    `id: ${v.id}`,\n    `subject: eip155:${v.subject.chainId}:${v.subject.token.toLowerCase()}`,\n    `verdict: ${v.verdict}`,\n    `risk_bps: ${v.riskBps}`,\n    `confidence_bps: ${v.confidenceBps}`,\n    `policy: ${v.policy.id}@${v.policy.version}`,\n    `engine: ${v.engineVersion}`,\n    `verdict_hash: ${v.verdictHash}`,\n    `bom_root: ${v.bom.root}`,\n    `price_usdc: ${v.cost.priceUsdc}`,\n    `upstream_usdc: ${v.cost.upstreamUsdc}`,\n    `network: ${v.network}`,\n    `created_at: ${v.createdAt}`,\n  ].join(\"\\n\");\n}\n\nexport interface Attestation {\n  scheme: typeof ATTESTATION_SCHEME;\n  signer: string;\n  message: string;\n  signature: string;\n}\n"],"mappings":";AAYA,SAAS,qBAAqB;;;ACavB,IAAM,oBAAoB;AAE1B,SAAS,mBAAmB,GAA4B;AAC7D,SAAO;AAAA,IACL;AAAA,IACA,OAAO,EAAE,EAAE;AAAA,IACX,mBAAmB,EAAE,QAAQ,OAAO,IAAI,EAAE,QAAQ,MAAM,YAAY,CAAC;AAAA,IACrE,YAAY,EAAE,OAAO;AAAA,IACrB,aAAa,EAAE,OAAO;AAAA,IACtB,mBAAmB,EAAE,aAAa;AAAA,IAClC,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,OAAO;AAAA,IAC1C,WAAW,EAAE,aAAa;AAAA,IAC1B,iBAAiB,EAAE,WAAW;AAAA,IAC9B,aAAa,EAAE,IAAI,IAAI;AAAA,IACvB,eAAe,EAAE,KAAK,SAAS;AAAA,IAC/B,kBAAkB,EAAE,KAAK,YAAY;AAAA,IACrC,YAAY,EAAE,OAAO;AAAA,IACrB,eAAe,EAAE,SAAS;AAAA,EAC5B,EAAE,KAAK,IAAI;AACb;;;ADnBA,eAAsB,kBAAkB,GAA2D,MAAqD;AACtJ,QAAM,IAAI,EAAE;AACZ,MAAI,CAAC,EAAG,QAAO,EAAE,IAAI,OAAO,QAAQ,MAAM,UAAU,CAAC,yEAAyE,EAAE;AAChI,QAAM,WAAqB,CAAC;AAC5B,MAAI,EAAE,WAAW,SAAU,UAAS,KAAK,kBAAkB,EAAE,MAAM,EAAE;AACrE,MAAI,EAAE,OAAO,YAAY,MAAM,KAAK,OAAO,YAAY,EAAG,UAAS,KAAK,aAAa,EAAE,MAAM,sBAAsB,KAAK,MAAM,EAAE;AAChI,QAAM,UAAU,mBAAmB,CAAC;AACpC,MAAI,YAAY,EAAE,QAAS,UAAS,KAAK,wDAAwD;AACjG,MAAI,QAAQ;AACZ,MAAI;AACF,YAAQ,MAAM,cAAc,EAAE,SAAS,KAAK,QAAyB,SAAS,SAAS,WAAW,EAAE,UAA2B,CAAC;AAAA,EAClI,QAAQ;AACN,YAAQ;AAAA,EACV;AACA,MAAI,CAAC,MAAO,UAAS,KAAK,wEAAwE;AAClG,SAAO,EAAE,IAAI,SAAS,WAAW,GAAG,QAAQ,EAAE,QAAQ,SAAS;AACjE;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,187 @@
+import { T as TelegraphAsker, S as Subject, Q as Quote, V as VerdictObject, B as Bom, a as VerifyReport, b as VerdictEvent } from './types-B_RIoOCq.js';
+export { A as Attestation, c as BomLine, C as CheckStatus, F as Finding, d as TelegraphAskOutcomeFail, e as TelegraphAskOutcomeOk, f as Verdict } from './types-B_RIoOCq.js';
+
+/** One parsed server-sent event. */
+interface RawEvent {
+    event: string;
+    data: string;
+    id?: string;
+}
+/**
+ * Parses a text/event-stream body into events (WHATWG rules: fields per line,
+ * a blank line dispatches, "data" lines join with \n, ":" lines are comments).
+ * Works on any fetch Response, in Node or the browser.
+ */
+declare function parseSse(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<RawEvent>;
+
+/** The intent Skein serves on Telegraph (plan A; see miner/INTENT.md). */
+declare const SKEIN_INTENT = "FRAUD_RISK_TOKEN_LISTING";
+/**
+ * How a verdict is paid for:
+ * - apiKey: a Skein partner key against the HTTP API (free during the hackathon);
+ * - telegraph: one paid Telegraph ask, routed to the Skein miner or pinned to it.
+ *   `client` is any Telegraph client, e.g. new TelegraphClient(...) from @skeinlabs/sdk/telegraph,
+ *   which enforces its own per-call price cap on the 402 challenge.
+ */
+type Payer = {
+    kind: "apiKey";
+    key: string;
+} | {
+    kind: "telegraph";
+    client: TelegraphAsker;
+    minerId?: string;
+    intent?: string;
+};
+interface SkeinOptions {
+    /** e.g. https://api.skeinlabs.site (with or without /v1). */
+    apiUrl: string;
+    payer?: Payer;
+    /** Refuse, before paying, any verdict whose quoted price is above this. */
+    maxUsdcPerCall?: number;
+    /** Retries for network errors, 429 and retryable 5xx. Default 2. */
+    retries?: number;
+    /** The most the SDK sleeps between retries of one call, in total; a longer Retry-After throws instead. Default 10 s. */
+    maxRetryWaitMs?: number;
+    /** Each HTTP request (submit, quote, get, verify) gives up after this. Default 15 s. */
+    requestTimeoutMs?: number;
+    /** How long verdict() waits for a result. Default 120 s. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+interface VerdictRequest {
+    subject: Subject;
+    /** "dex-list@0.1.0", or an id for its latest version. */
+    policy?: string;
+    /**
+     * Optional evidence about the project. socialHandle buys the social-bot
+     * check, repoUrl (github.com or gitlab.com) buys the code review.
+     * `social` and `repo` are accepted as aliases.
+     */
+    context?: VerdictContextInput;
+    /** Reuse to make a retried call return the original verdict. Generated when omitted. */
+    idempotencyKey?: string;
+    /** Called with each live event (API key path). */
+    onEvent?: (e: VerdictEvent) => void;
+    signal?: AbortSignal;
+    /** A quote you already fetched for this request, so verdict() does not fetch another. */
+    quote?: Quote;
+}
+interface VerdictContextInput {
+    deployer?: string;
+    socialHandle?: string;
+    repoUrl?: string;
+    treasuryAddresses?: string[];
+    pool?: string;
+    /** Alias of socialHandle. */
+    social?: string;
+    /** Alias of repoUrl. */
+    repo?: string;
+}
+/** The API's field names: aliases mapped, empty values dropped. */
+declare function canonicalContext(c: VerdictContextInput | undefined): Record<string, unknown> | undefined;
+type Payment = {
+    rail: "apiKey";
+} | {
+    rail: "telegraph";
+    minerId: string;
+    amountUsdc: number;
+    receiptHash: string | null;
+    signalHash: string | null;
+};
+type VerdictResult = VerdictObject & {
+    payment: Payment;
+};
+/** Every API error, with the API's code (BUDGET_TOO_LOW, RATE_LIMITED, …) or an SDK code. */
+declare class SkeinError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly details?: unknown | undefined;
+    /**
+     * Set when money moved (or may have) before the failure: a Telegraph ask
+     * that was paid but produced no verdict. Count it against your caps.
+     */
+    readonly payment?: {
+        amountUsdc: number;
+        billing: "paid" | "unknown";
+        receiptHash?: string | null;
+    } | undefined;
+    constructor(code: string, message: string, status?: number, details?: unknown | undefined, 
+    /**
+     * Set when money moved (or may have) before the failure: a Telegraph ask
+     * that was paid but produced no verdict. Count it against your caps.
+     */
+    payment?: {
+        amountUsdc: number;
+        billing: "paid" | "unknown";
+        receiptHash?: string | null;
+    } | undefined);
+}
+/** The quoted price is above maxUsdcPerCall; nothing was paid. */
+declare class SpendCapError extends SkeinError {
+    readonly priceUsdc: number;
+    readonly capUsdc: number;
+    constructor(priceUsdc: number, capUsdc: number);
+}
+declare class Skein {
+    private readonly opts;
+    private readonly base;
+    private readonly fetch;
+    private readonly retries;
+    private readonly timeoutMs;
+    constructor(opts: SkeinOptions);
+    private readonly maxRetryWaitMs;
+    private readonly requestTimeoutMs;
+    /** One HTTP request with its own deadline, still cancellable by the caller's signal. */
+    private request;
+    /**
+     * A raw call with typed errors and retries. POSTs are retried only with an
+     * idempotency key. Retries sleep at most maxRetryWaitMs in total: a
+     * Retry-After past that (a daily cap until midnight) throws at once.
+     */
+    private call;
+    /** What a verdict would buy and cost, without buying. Free. */
+    quote(req: {
+        subject: Subject;
+        policy?: string;
+    }): Promise<Quote>;
+    /** A stored verdict, or { status: "running" } while it is being made. */
+    get(id: string): Promise<VerdictObject | {
+        id: string;
+        status: "running";
+    }>;
+    /** The bill of materials: every paid input and its receipt. */
+    bom(id: string): Promise<Bom>;
+    /** Recompute a verdict from its raw paid answers. */
+    verify(id: string): Promise<VerifyReport>;
+    /** The live events of a verdict, replayed from the start; ends after done, refused or error. */
+    stream(id: string, opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<VerdictEvent>;
+    /**
+     * Buys one verdict and returns it once it is sealed. With maxUsdcPerCall
+     * set, the price is quoted first and the call refused before any payment.
+     */
+    verdict(req: VerdictRequest): Promise<VerdictResult>;
+    /**
+     * Starts a verdict on the partner-key rail and returns at once: the id while
+     * it runs, or the verdict itself when it is cached or replayed. Pair with
+     * wait(id). Spend-cap checks are the caller's (verdict() does them).
+     */
+    submit(req: VerdictRequest): Promise<{
+        id: string;
+        status: "running";
+    } | VerdictResult>;
+    /**
+     * Waits for a submitted verdict: follows its event stream (falling back to
+     * polling if the stream drops) and throws a SkeinError if it is refused.
+     */
+    wait(id: string, opts?: {
+        onEvent?: (e: VerdictEvent) => void;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<VerdictResult>;
+    private viaApi;
+    private viaTelegraph;
+}
+
+export { Bom, type Payer, type Payment, Quote, SKEIN_INTENT, Skein, SkeinError, type SkeinOptions, SpendCapError, Subject, TelegraphAsker, type VerdictContextInput, VerdictEvent, VerdictObject, type VerdictRequest, type VerdictResult, VerifyReport, canonicalContext, parseSse };