@ixo/openhands-sdk 0.0.0-stage → 0.1.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,247 @@
-# Temporary Holding Version
+# @ixo/openhands-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.
+One SDK for building on the Openhands Network: the protocol shapes, readers of the index and the
+document stores, browser signing, the meaning of an ask's terms, signed determinations (UDID),
+geo helpers, and the cleanup-campaign kit. It replaces seven packages that used to live beside
+each other in this monorepo (see [docs/migration.md](docs/migration.md)).
+
+- [docs/front-end-guide.md](docs/front-end-guide.md): build a specialised front end on the network
+- [docs/campaign-guide.md](docs/campaign-guide.md): the cleanup campaign kit, and what it assumes
+- [docs/config-reference.md](docs/config-reference.md): every configuration field, env variable and default
+- [docs/migration.md](docs/migration.md): old specifier to new, constants to functions
+
+## Status
+
+Apache-2.0 (see [LICENSE](LICENSE)), published to npm as `@ixo/openhands-sdk` once 0.1.0 is out;
+until then it is not on npm. In git, `package.json` carries the placeholder version `0.0.0-development`
+(semantic-release sets the real one inside the release job). The consumers today are:
+
+- this monorepo (the main app, the worker, the MCP server, scripts), through a TypeScript path;
+- the MCP server, which bundles it into `@ixo/openhands-mcp`;
+- the youth app, which now lives in its own repo (`openhands-youth`) and **vendors** a copy of this
+  package under `vendor/openhands-sdk` until 0.1.0 is published, then moves to the npm package (see
+  [docs/youth-app.md](../../docs/youth-app.md)).
+
+## Install
+
+**In this monorepo.** No install. `tsconfig.json` maps `@ixo/openhands-sdk/*` to
+`packages/openhands-sdk/src/*`, so `import { parseQuery } from "@ixo/openhands-sdk/data/board/query"`
+works in `app/`, `workers/`, `services/` and `scripts/`.
+
+**In another repo, once 0.1.0 is published.**
+
+```bash
+npm i @ixo/openhands-sdk     # or: pnpm add @ixo/openhands-sdk
+```
+
+The package ships both ESM and CommonJS, with type declarations, built into `dist/`. Import a
+subpath, never the package root (there is none):
+
+```ts
+// ESM (and TypeScript)
+import { parseQuery } from "@ixo/openhands-sdk/data/board/query";
+
+// CommonJS
+const { parseQuery } = require("@ixo/openhands-sdk/data/board/query");
+```
+
+The subpaths are the barrels `protocol`, `board`, `campaign`, `geo`, `udid`, `rubric`, `chain`
+and `config`, the server-only `data` barrel, and the wildcards `data/*`, `chain/*`, `rubric/*`,
+`geo/*`, `udid/*` and `campaign/*` for single modules.
+
+Peer dependencies your app must hold (the chain stack it has anyway):
+
+```
+@cosmjs/crypto @cosmjs/encoding @cosmjs/proto-signing @cosmjs/stargate ^0.39.0
+@ixo/impactxclient-sdk 3.0.0     @ixo/ucan ^2.1.0
+```
+
+`long` and `zod` come with the package as its own dependencies.
+
+Node: ESM consumers need Node 22 or newer. CommonJS consumers need Node 22.12 or newer, because one
+dependency is ESM-only and is loaded through `require(esm)`.
+
+TypeScript: keep `skipLibCheck: true` (the default in a Next project). The SDK's own declarations
+check clean under `moduleResolution` `node16` and `bundler`, for `import` and `require`; the chain
+packages' declarations (`@cosmjs/*`, `@ixo/impactxclient-sdk`) do not pass a strict library check.
+
+**In another repo, today (before 0.1.0).** Vendor the folder (copy `packages/openhands-sdk` into
+your repo and point a path mapping at it), and make your bundler compile it: the source is
+TypeScript (`./src/*.ts`, ESM, `.ts` import specifiers). For Next.js add it to `transpilePackages`
+(or keep it inside your own source tree so it is compiled with your app). Install the same peer
+dependencies as above. Node >= 22.6 (the tests run on `--experimental-strip-types`).
+
+## Configure
+
+The SDK reads nothing at import. There is **no single configuration object that every module
+reads**: each setting is an accessor that sits next to the module that uses it (`rpcUrl()` in
+`chain/env`, `vfsUrl()` in `data/docUrls`, `askDenom()` in `chain/money`, `workerUrl()` in
+`campaign/fold`, `checkerBaseUpay()` in `rubric/leg`, ...). What `configure()` received is held in
+`src/given.ts`; `src/network.ts` holds `network()` (validated lazily) and the env helpers. Each
+accessor is resolved **at call time**, with no memo of its own, from, in order:
+
+1. what you passed to `configure()`;
+2. the environment variable the code has always read (same names, so the two Next apps, the
+   workers and the scripts need no change);
+3. the per-network default (the endpoint tables live beside their accessors: chain endpoints in
+   `chain/env`, VFS in `data/docUrls`).
+
+Why no single `config()` read in browser code: a call to `config()` composes every setting, so it
+would pull every table and every module's defaults into any bundle that touched it. Browser code
+imports just the accessor it needs and pays only for that. `config()` still exists in
+`@ixo/openhands-sdk/config` for hosts that want the whole object (it composes it from the
+accessors and memoises the result; `configure()` and `resetConfig()` drop it), but no SDK module
+other than `config.ts` calls it (`barrels.test.ts` enforces that, and that the tables appear
+nowhere else).
+
+```ts
+import { configure } from "@ixo/openhands-sdk/config";
+
+configure({
+  network: "testnet",                         // devnet | testnet | mainnet (anything else throws)
+  graphqlUrl: "https://testnet-blocksync-graphql.ixo.earth/graphql",
+  workerUrl: "https://api.example.org",
+  granterBotUrl: "https://api.example.org",   // the submission gate's base URL
+  granterAddress: "ixo1...",                  // the gate's address
+});
+```
+
+- **Browser / Next.** `NEXT_PUBLIC_*` literals are inlined by Next at build time. The SDK reads
+  them with literal property accesses (`process.env.NEXT_PUBLIC_X`), which is the only form Next
+  inlines. Changing one needs a rebuild.
+- **Cloudflare Worker.** Bindings are not `process.env`. Either call `configure()` from your
+  handler with values from `env` before using the SDK, or copy the string bindings onto
+  `process.env` (with `nodejs_compat`) and call `invalidateGiven()` from
+  `@ixo/openhands-sdk/given` once per event so a composed `config()` read never goes stale.
+  The openhands worker does the second, through `given.ts` on purpose: importing `config.ts`
+  would load every accessor and the chain stack at startup.
+- **No `process` at all.** The environment reads as empty; call `configure()`.
+- **Configure before the first call.** Two modules cache on first use and do not watch for a
+  later `configure()`: `chain/query` keeps its query client (made with the first `rpcUrl()`), and
+  `data/denoms` keeps its primed denom table. Pass your settings before anything else runs.
+
+Full table (field, variable, default, which modules read it): [docs/config-reference.md](docs/config-reference.md).
+`resetConfig()` forgets what `configure()` was given (tests).
+
+## Subpaths
+
+There is **no root export**: you import a subpath. Barrels re-export only isomorphic modules;
+anything else is reachable by its own subpath.
+
+| Subpath | What it is for | Runs in |
+| --- | --- | --- |
+| `./config` | `configure()`, `config()` (the whole object, for hosts that want it), `resetConfig()`, `defaultsFor()`, `NETWORKS` | anywhere |
+| `./protocol` | The shapes every front end shares: envelopes, verdicts, proofs, resources, the UDID schema/wrapper/verify/resolve, ask terms, the claim form, the evaluation leg, the agent card, `money`, `iid`, `accountProof`, `grantPending` | isomorphic |
+| `./board` | The board's pure pieces: query parsing and URLs, assembly, ranking, coverage, series, trust. The loader `data/board/read` is subpath-only | isomorphic |
+| `./campaign` | The cleanup campaign: spots, pins, the fold, pools, pledges, funding, standings, badges, bands. `campaign/rule` is types only here | isomorphic |
+| `./geo` | Boxes, tiles, EXIF, sun position, OSM and Nominatim search | isomorphic |
+| `./udid` | The UDID envelope: schema, canonical form, CIDs, keys, verification, DID resolution | isomorphic |
+| `./rubric` | Ask terms, the rubric bridge to the engine, the claim form, the evaluation leg, the agent card, drafting, publishing | isomorphic |
+| `./chain` | Accounts, asks, allowances, delegation, guests, broadcast, the store, the session. Deliberately small: pages load it with `await import()` | isomorphic (browser signing) |
+| `./data` | Server-only barrel over the readers (`gql`, `loadReceipt`, `loadThreads`, ...) | server |
+| `./data/*`, `./chain/*`, `./rubric/*`, `./geo/*`, `./udid/*`, `./campaign/*` | Any single module, e.g. `./data/receipt`, `./chain/guest`, `./rubric/terms`, `./campaign/pool` | per module |
+
+**Three modules need `node:crypto` and are subpath-only**, never in a barrel:
+
+| Module | Why |
+| --- | --- |
+| `@ixo/openhands-sdk/chain/signx` | SignX session signing |
+| `@ixo/openhands-sdk/data/cid` | synchronous CID hashing (the isomorphic form is `udid/cid`, or `cidOfTextAsync` in `data/cid`) |
+| `@ixo/openhands-sdk/campaign/rule` | hashes the sealed rule; `campaign` re-exports its types only |
+
+## Tree-shaking rules
+
+1. No root export; import subpaths.
+2. `"sideEffects": false`: bundlers may drop any import that is unused.
+3. Nothing runs at import: no environment reads, no network, no globals touched. Settings are
+   per-module accessors, not one shared read, so importing one module never drags in the others'
+   tables; only `config.ts` imports `config.ts` at runtime.
+   [`src/import-safety.test.ts`](src/import-safety.test.ts) enforces it.
+4. Barrels re-export only isomorphic modules: no `node:` builtin and no server-only package
+   anywhere in their import graph. [`src/barrels.test.ts`](src/barrels.test.ts) walks the graph
+   and fails if one appears.
+5. In browser code, prefer the narrowest subpath that has what you need (`./data/board/query`,
+   not `./board`, if you only parse a URL). `chain` and `rubric` carry more than most pages need;
+   several modules are left out of the barrel for exactly that reason and say so in its header
+   (`chain/sponsor`, `chain/signWith`, `rubric/roundTrips`, ...).
+
+## The campaign subpath
+
+`./campaign` is the cleanup campaign as a kit: pin a mess (a "spot") on a map, pool money
+against it, record pledges, fold a campaign's asks into one readable shape, rank people without
+naming them, award badges, and seal and reveal a funding rule. The youth app is built on it.
+Another campaign can reuse the generic half (the fold, pool arithmetic, pledges and their memo
+grammar, standings, the sealed rule) and replace the cleanup-specific half (bands, the spot
+assessment, the cleanup/field/commitment terms). What is which, with file citations:
+[docs/campaign-guide.md](docs/campaign-guide.md).
+
+## Examples
+
+Read the board's grammar and the public board (`/api/board` is a main-app route, not an SDK call):
+
+```ts
+import { parseQuery, queryString } from "@ixo/openhands-sdk/data/board/query";
+
+const query = parseQuery(new URL("https://x.test/?kind=photo&near=-26.20,28.04&km=10").searchParams);
+const path = `/api/board${queryString(query)}`;
+```
+
+Read what an ask's terms mean:
+
+```ts
+import { deriveTerms, askSentence, parseTerms } from "@ixo/openhands-sdk/rubric/terms";
+
+const terms = deriveTerms("Photograph the notice board at the library");
+askSentence(terms);              // the criteria, as one sentence
+parseTerms(JSON.parse(text));    // AskTerms | null for a published terms document
+```
+
+Price a spot (reads `askDenom()` and `checkRewardBase()`, each resolved at call time):
+
+```ts
+import { billFor } from "@ixo/openhands-sdk/campaign/funding";
+
+const { workBase, legBase, targetBase } = billFor(spot);   // billFor(spot, denom?, checkBase?)
+```
+
+Check a determination (UDID):
+
+```ts
+import { verifyUdid } from "@ixo/openhands-sdk/udid/verify";
+import { keysFor } from "@ixo/openhands-sdk/udid/resolve";
+
+const [key] = await keysFor(wrapper.payload.iss);
+const result = await verifyUdid(wrapper.jws, { publicKeyRaw: key.raw, expectedCid: wrapper.cid });
+```
+
+A walk-through that ends in a signed submission is in [docs/front-end-guide.md](docs/front-end-guide.md).
+
+## Publishing
+
+`pnpm -C packages/openhands-sdk build` runs `build.mjs`: tsc twice, into `dist/esm` and
+`dist/cjs` (each with its own `package.json` type), and the manifest's `exports` map points every
+subpath at both, under `import` and `require`. Releases come from
+`main` by semantic-release with npm trusted publishing (OIDC, no npm token), through
+`.github/workflows/release-sdk.yml` and `packages/openhands-sdk/.releaserc.json`, tagged
+`sdk-v<version>`. Only commits scoped `sdk` release it (`feat(sdk)` a minor, `fix(sdk)` a patch),
+and an `sdk` commit also releases `@ixo/openhands-mcp`, which bundles the SDK. The first version,
+0.1.0, is published by hand from a laptop (the package does not exist on npm until then), and
+the one-time setup is in [docs/RELEASING-MCP.md](../../docs/RELEASING-MCP.md), which covers both
+packages.
+
+Once 0.1.0 is published, the youth app swaps its vendored copy for the dependency.
+
+## Versioning
+
+Semver. The public surface is the set of subpaths in `exports` and what they export. Breaking: removing or
+renaming a subpath or an export, changing a function's parameters or return shape, changing what
+a barrel contains (membership of `chain` is deliberately small, adding to it is a bundle-size
+change for every page). Config: a new `OpenhandsConfig` field with a default is minor; changing a
+default or an env variable's meaning is breaking. While `0.x`, minor bumps may break.
+
+## Checks
+
+```bash
+pnpm test:sdk                          # from the monorepo root
+pnpm -C packages/openhands-sdk typecheck
+```

package/dist/cjs/board.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@ixo/openhands-sdk/board` — the board's pure pieces: query parsing and URLs, assembly, ranking, coverage, series and trust. The loader (`data/board/read`) is subpath-only: it reads the index and reaches the campaign layer.
+ *
+ * Isomorphic by contract: nothing reachable from here imports a `node:`
+ * builtin or a server-only package (`barrels.test.ts` walks the graph and
+ * fails if one appears), so a browser bundle can import this barrel. A module
+ * that needs Node stays reachable only by its own subpath.
+ */
+export * from "./data/board/types.ts";
+export * from "./data/board/query.ts";
+export * from "./data/board/url.ts";
+export * from "./data/board/assemble.ts";
+export * from "./data/board/rank.ts";
+export * from "./data/board/words.ts";
+export { asksNear, busiestPlaces, countedAsks, COVERAGE_DAYS, coverageOf, coverageWords, firstApprovals, PLACE_MIN, PLACES_MAX, POSTING_BACKDATE_MS, toTime, townOf, waitWords, type Coverage, type CoverageAnswer, type CoveragePlace, type CoveragePlacesAnswer } from "./data/board/coverage.ts";
+export * from "./data/board/series.ts";
+export { FAST_MIN_PAID, FAST_MINUTES, medianOf, trustOf, trustWords, TIMED_MIN as TRUST_TIMED_MIN } from "./data/board/trust.ts";
+export { TIMED_MIN as COVERAGE_TIMED_MIN } from "./data/board/coverage.ts";
+export * from "./data/board/facts.ts";
+//# sourceMappingURL=board.d.ts.map

package/dist/cjs/board.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.d.ts","sourceRoot":"","sources":["../../src/board.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACL,QAAQ,EACR,aAAa,EACb,WAAW,EACX,aAAa,EACb,UAAU,EACV,aAAa,EACb,cAAc,EACd,SAAS,EACT,UAAU,EACV,mBAAmB,EACnB,MAAM,EACN,MAAM,EACN,SAAS,EACT,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,cAAc,wBAAwB,CAAC;AAIvC,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,IAAI,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACjI,OAAO,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,cAAc,uBAAuB,CAAC"}

package/dist/cjs/board.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * `@ixo/openhands-sdk/board` — the board's pure pieces: query parsing and URLs, assembly, ranking, coverage, series and trust. The loader (`data/board/read`) is subpath-only: it reads the index and reaches the campaign layer.
+ *
+ * Isomorphic by contract: nothing reachable from here imports a `node:`
+ * builtin or a server-only package (`barrels.test.ts` walks the graph and
+ * fails if one appears), so a browser bundle can import this barrel. A module
+ * that needs Node stays reachable only by its own subpath.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COVERAGE_TIMED_MIN = exports.TRUST_TIMED_MIN = exports.trustWords = exports.trustOf = exports.medianOf = exports.FAST_MINUTES = exports.FAST_MIN_PAID = exports.waitWords = exports.townOf = exports.toTime = exports.POSTING_BACKDATE_MS = exports.PLACES_MAX = exports.PLACE_MIN = exports.firstApprovals = exports.coverageWords = exports.coverageOf = exports.COVERAGE_DAYS = exports.countedAsks = exports.busiestPlaces = exports.asksNear = void 0;
+__exportStar(require("./data/board/types.js"), exports);
+__exportStar(require("./data/board/query.js"), exports);
+__exportStar(require("./data/board/url.js"), exports);
+__exportStar(require("./data/board/assemble.js"), exports);
+__exportStar(require("./data/board/rank.js"), exports);
+__exportStar(require("./data/board/words.js"), exports);
+var coverage_ts_1 = require("./data/board/coverage.js");
+Object.defineProperty(exports, "asksNear", { enumerable: true, get: function () { return coverage_ts_1.asksNear; } });
+Object.defineProperty(exports, "busiestPlaces", { enumerable: true, get: function () { return coverage_ts_1.busiestPlaces; } });
+Object.defineProperty(exports, "countedAsks", { enumerable: true, get: function () { return coverage_ts_1.countedAsks; } });
+Object.defineProperty(exports, "COVERAGE_DAYS", { enumerable: true, get: function () { return coverage_ts_1.COVERAGE_DAYS; } });
+Object.defineProperty(exports, "coverageOf", { enumerable: true, get: function () { return coverage_ts_1.coverageOf; } });
+Object.defineProperty(exports, "coverageWords", { enumerable: true, get: function () { return coverage_ts_1.coverageWords; } });
+Object.defineProperty(exports, "firstApprovals", { enumerable: true, get: function () { return coverage_ts_1.firstApprovals; } });
+Object.defineProperty(exports, "PLACE_MIN", { enumerable: true, get: function () { return coverage_ts_1.PLACE_MIN; } });
+Object.defineProperty(exports, "PLACES_MAX", { enumerable: true, get: function () { return coverage_ts_1.PLACES_MAX; } });
+Object.defineProperty(exports, "POSTING_BACKDATE_MS", { enumerable: true, get: function () { return coverage_ts_1.POSTING_BACKDATE_MS; } });
+Object.defineProperty(exports, "toTime", { enumerable: true, get: function () { return coverage_ts_1.toTime; } });
+Object.defineProperty(exports, "townOf", { enumerable: true, get: function () { return coverage_ts_1.townOf; } });
+Object.defineProperty(exports, "waitWords", { enumerable: true, get: function () { return coverage_ts_1.waitWords; } });
+__exportStar(require("./data/board/series.js"), exports);
+/* `trust` and `coverage` each define a different `TIMED_MIN` (5 and 3), so
+   both are listed by name and the two thresholds are renamed here rather
+   than one silently shadowing the other. The subpaths keep the plain names. */
+var trust_ts_1 = require("./data/board/trust.js");
+Object.defineProperty(exports, "FAST_MIN_PAID", { enumerable: true, get: function () { return trust_ts_1.FAST_MIN_PAID; } });
+Object.defineProperty(exports, "FAST_MINUTES", { enumerable: true, get: function () { return trust_ts_1.FAST_MINUTES; } });
+Object.defineProperty(exports, "medianOf", { enumerable: true, get: function () { return trust_ts_1.medianOf; } });
+Object.defineProperty(exports, "trustOf", { enumerable: true, get: function () { return trust_ts_1.trustOf; } });
+Object.defineProperty(exports, "trustWords", { enumerable: true, get: function () { return trust_ts_1.trustWords; } });
+Object.defineProperty(exports, "TRUST_TIMED_MIN", { enumerable: true, get: function () { return trust_ts_1.TIMED_MIN; } });
+var coverage_ts_2 = require("./data/board/coverage.js");
+Object.defineProperty(exports, "COVERAGE_TIMED_MIN", { enumerable: true, get: function () { return coverage_ts_2.TIMED_MIN; } });
+__exportStar(require("./data/board/facts.js"), exports);
+//# sourceMappingURL=board.js.map

package/dist/cjs/board.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board.js","sourceRoot":"","sources":["../../src/board.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;AAEH,wDAAsC;AACtC,wDAAsC;AACtC,sDAAoC;AACpC,2DAAyC;AACzC,uDAAqC;AACrC,wDAAsC;AACtC,wDAkBkC;AAjBhC,uGAAA,QAAQ,OAAA;AACR,4GAAA,aAAa,OAAA;AACb,0GAAA,WAAW,OAAA;AACX,4GAAA,aAAa,OAAA;AACb,yGAAA,UAAU,OAAA;AACV,4GAAA,aAAa,OAAA;AACb,6GAAA,cAAc,OAAA;AACd,wGAAA,SAAS,OAAA;AACT,yGAAA,UAAU,OAAA;AACV,kHAAA,mBAAmB,OAAA;AACnB,qGAAA,MAAM,OAAA;AACN,qGAAA,MAAM,OAAA;AACN,wGAAA,SAAS,OAAA;AAMX,yDAAuC;AACvC;;+EAE+E;AAC/E,kDAAiI;AAAxH,yGAAA,aAAa,OAAA;AAAE,wGAAA,YAAY,OAAA;AAAE,oGAAA,QAAQ,OAAA;AAAE,mGAAA,OAAO,OAAA;AAAE,sGAAA,UAAU,OAAA;AAAE,2GAAA,SAAS,OAAmB;AACjG,wDAA2E;AAAlE,iHAAA,SAAS,OAAsB;AACxC,wDAAsC"}

package/dist/cjs/campaign/badges.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What somebody has to show for it.
+ *
+ * A badge is a **count of approved claims**, never a number we keep — so it
+ * is re-derivable by anyone who can read the chain, which is what makes it
+ * portable to any surface that ever wants to render it. Nothing is issued
+ * here: a badge is a reading of the chain, and the signed credential that
+ * makes one portable is minted elsewhere from these same counts.
+ *
+ * The table is the one place a threshold lives, so `/me`, a certificate page
+ * and a share card can never disagree about what somebody earned.
+ */
+export type { Record_ } from "./record.ts";
+import type { Record_ } from "./record.ts";
+export interface Badge {
+    key: string;
+    emoji: string;
+    /** The plain English label. A youth app may render its own wording from
+     *  `key`; a credential and a share card need words that travel. */
+    title: string;
+    /** What earns it. */
+    need: (record: Record_) => boolean;
+    /** How far along, for a ring on a page that shows one. */
+    progress: (record: Record_) => number;
+    /** The line a card says about it. */
+    count: (record: Record_) => number;
+}
+export declare const BADGES: Badge[];
+export declare const badgeFor: (key: string) => Badge | null;
+//# sourceMappingURL=badges.d.ts.map

package/dist/cjs/campaign/badges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"badges.d.ts","sourceRoot":"","sources":["../../../src/campaign/badges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd;uEACmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;IACtC,qCAAqC;IACrC,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,MAAM,CAAC;CACpC;AAID,eAAO,MAAM,MAAM,EAAE,KAAK,EAiDzB,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,KAAK,GAAG,IAAqD,CAAC"}

package/dist/cjs/campaign/badges.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * What somebody has to show for it.
+ *
+ * A badge is a **count of approved claims**, never a number we keep — so it
+ * is re-derivable by anyone who can read the chain, which is what makes it
+ * portable to any surface that ever wants to render it. Nothing is issued
+ * here: a badge is a reading of the chain, and the signed credential that
+ * makes one portable is minted elsewhere from these same counts.
+ *
+ * The table is the one place a threshold lives, so `/me`, a certificate page
+ * and a share card can never disagree about what somebody earned.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.badgeFor = exports.BADGES = void 0;
+const ratio = (have, want) => Math.max(0, Math.min(1, have / want));
+exports.BADGES = [
+    {
+        key: "first-find",
+        emoji: "🔎",
+        title: "First find",
+        need: (r) => r.spotted >= 1,
+        progress: (r) => ratio(r.spotted, 1),
+        count: (r) => r.spotted
+    },
+    {
+        key: "spotter-5",
+        emoji: "🕵️",
+        title: "Five finds",
+        need: (r) => r.spotted >= 5,
+        progress: (r) => ratio(r.spotted, 5),
+        count: (r) => r.spotted
+    },
+    {
+        key: "cleaner-1",
+        emoji: "🧹",
+        title: "Cleaned one",
+        need: (r) => r.cleaned >= 1,
+        progress: (r) => ratio(r.cleaned, 1),
+        count: (r) => r.cleaned
+    },
+    {
+        key: "cleaner-5",
+        emoji: "🌟",
+        title: "Cleaned five",
+        need: (r) => r.cleaned >= 5,
+        progress: (r) => ratio(r.cleaned, 5),
+        count: (r) => r.cleaned
+    },
+    {
+        key: "backer-1",
+        emoji: "💚",
+        title: "Backed a cleanup",
+        need: (r) => r.backed >= 1,
+        progress: (r) => ratio(r.backed, 1),
+        count: (r) => r.backed
+    },
+    {
+        key: "crew-1",
+        emoji: "🙋",
+        title: "Joined a crew",
+        need: (r) => r.committed >= 1,
+        progress: (r) => ratio(r.committed, 1),
+        count: (r) => r.committed
+    }
+];
+const badgeFor = (key) => exports.BADGES.find((one) => one.key === key) ?? null;
+exports.badgeFor = badgeFor;
+//# sourceMappingURL=badges.js.map

package/dist/cjs/campaign/badges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"badges.js","sourceRoot":"","sources":["../../../src/campaign/badges.ts"],"names":[],"mappings":"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"}