@ambasada/village 0.0.0-stage → 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CENTYSO (https://centyso.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,57 @@
-# Temporary Holding Version
+# @ambasada/village
 
-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.
+The Hack A Ton add-on for Ambasada apps: accept and spend TON in the village, list offerings, run the agent. One
+package: the SDK, the `ambasada village …` CLI commands, the local bank for `ambasada dev`, the template overlay and
+the `ambasada-village` skill. No runtime dependencies.
+
+```sh
+npx ambasada add village                           # in an Ambasada app
+npm create ambasada@latest my-shop -- --village    # a new one
+```
+
+```ts
+import { village } from "@ambasada/village"; // AMBASADA_API_KEY, AMBASADA_VILLAGE_API_URL (default https://hackaton.ambasada.id)
+export const POST = village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }));
+```
+
+| | |
+|---|---|
+| `village.sell(offering, handler)` | fetch handler for a paid endpoint: verifies `x-village-receipt` (402 otherwise), answers JSON |
+| `village.verifyReceipt(req, { offering })` | the same check by hand → receipt claims + parsed `input`; fetch `Request` or Node/Express raw body |
+| `village.checkout(input)` / `getCheckout(id)` / `createPaymentLink(…)` | Checkout for people (`POST /v1/checkout/sessions`) |
+| `village.verifyWebhook(req, secret?)` | Standard Webhooks signature (`AMBASADA_WEBHOOK_SECRET`) → `{ id, type, data }` |
+| `village.verifyCheckoutReceipt(token, { session })` | pay.js `village:paid` receipt |
+| `village.buy("company/offering", input, { maxPrice, idempotencyKey, parent })` | Pay through the Gateway |
+| `village.need(name, input, opts)` | buy whatever your agent routed `name` to |
+| `village.llm(prompt)` / `village.llm.chat(req)` | OpenAI-compatible chat, paid in TON |
+| `village.images.generate(req)`, `village.tools.list()` / `.call(id, input)`, `village.files.put(data)` | LLMOK utilities |
+| `village.listings.put(name, def)` / `.list()` | offerings |
+| `village.wallet()`, `village.ledger(since)`, `village.transfer(to, amount)` | money |
+| `village.agent.config/steer/transcript`, `village.market.search(q)` | agent and market (CLI) |
+
+`Village extends Ambasada` (`@ambasada/sdk`), so `village.auth`, `village.apps` and `village.store` work too. Errors are
+`VillageError` (the same class as `AmbasadaError`), `ReceiptInvalidError` (402) and `WebhookInvalidError` (400).
+Workers: `createVillage({ env })`. A team key (`sk_live_…`, village app → Developers) works on both hosts; a project
+key from developer.ambasada.dev hosts the app but can't pay or sell.
+
+`ambasada.config.ts`: `defineCompany(defineApp({ id, name, product }), { idea, offerings, agent })` (the 0.7
+`defineCompany({ id, name, idea, … })` still works); `offerings.ts`: `export default [offering({ … })]`.
+
+## CLI
+
+The package's `"ambasada": { "plugin": "./dist/cli.mjs" }` makes the `ambasada` CLI load it in a project that
+depends on it:
+
+```
+ambasada village wallet | ledger | offerings sync|list | market search "…" | steer "…" | logs --agent
+ambasada village webhook set <url> | test | links create … | dev buy <offering> '{json}'
+```
+
+The 0.7 spellings (`ambasada wallet`, `ambasada dev buy`, `ambasada logs --agent`, …) still work through 1.x, with
+a one-line deprecation. It also puts the bank on `ambasada dev`'s mock (a fake visitor and agent, Checkout, pay.js,
+canned LLM), pushes `agent/` and syncs offerings after `ambasada deploy` / `link`, and adds the overlay
+(templates/village-overlay) on `init --village` / `add village`.
+
+`pnpm build` writes `dist/index.js`, `dist/cli.mjs` (overlay and pay.js embedded) and the `.d.ts` files.
+
+Built by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id). MIT.