aimeat 2.2.0 → 2.3.0

package/dist/static/sdk-libs/dist/aimeat-webmcp.js

@@ -94,6 +94,27 @@
       return asContent(res.ok ? res.data : res);
     };
   }
+  function aboutTool(ref, surface, toolCount) {
+    const s = surface || {};
+    const label = s.name || ref.appId;
+    const parts = [];
+    if (toolCount) parts.push(toolCount + " callable tool" + (toolCount === 1 ? "" : "s"));
+    if ((s.skills || []).length) parts.push(s.skills.length + " bound skill" + (s.skills.length === 1 ? "" : "s"));
+    if ((s.bundled_agents || []).length) parts.push(s.bundled_agents.length + " bundled agent" + (s.bundled_agents.length === 1 ? "" : "s"));
+    const offers = ((s.exchange || {}).offerings || []).length;
+    if (offers) parts.push(offers + " EXCHANGE listing" + (offers === 1 ? "" : "s"));
+    const carries = parts.length ? " Carries " + parts.join(", ") + "." : "";
+    return {
+      name: "about-this-app",
+      description: 'What "' + label + '" (' + ref.owner + "/" + ref.appId + ") offers an agent: its app id, declared scopes, the SKILL.md packs bound to it, the agent crews it ships, and what it sells on the AIMEAT EXCHANGE, with prices." + carries,
+      inputSchema: { type: "object", properties: {} },
+      async execute() {
+        if (surface) return asContent(surface);
+        const listing = await fetchListing(ref.owner, ref.appId);
+        return asContent(listing.app_surface || { app: ref.owner + "/" + ref.appId });
+      }
+    };
+  }
   var webmcp = {
     /** Every tool descriptor this page has registered (introspection + provideContext resends). */
     tools: [],
@@ -116,9 +137,15 @@
     /**
      * Expose an app's declared tools (apps.{appId}.tools manifest) to the in-browser agent.
      * Descriptions of priced tools carry the price tag so the agent can tell the user the cost.
+     *
+     * Every app also gets `about-this-app`, built from the listing's `app_surface`: the SKILL.md
+     * packs bound to the app, the crew-defs it ships, its declared scopes and its live EXCHANGE
+     * listings. An app that sells nothing still exposes that one, so an agent that lands on any
+     * app page can ask what it is looking at instead of reading 200 kB of minified source.
      */
     async exposeAppTools(ref) {
       const listing = await fetchListing(ref.owner, ref.appId);
+      const surface = listing.app_surface || null;
       const tools = (listing.tools || []).map(function(entry) {
         let desc = entry.description || entry.name;
         if (entry.payment && entry.payment.required) {
@@ -135,6 +162,7 @@
           execute: buildExecute(ref.owner, ref.appId, entry)
         };
       });
+      tools.unshift(aboutTool(ref, surface, tools.length));
       await webmcp.register(tools);
       return { surface: webmcp.surface, tools: tools.map(function(t) {
         return t.name;
@@ -169,6 +197,18 @@
     }
   };
   attach("webmcp", webmcp);
+  function appRefFromPage(el) {
+    const ds = el && el.dataset || {};
+    if (ds.owner && ds.app) return { owner: ds.owner, appId: ds.app };
+    try {
+      const node = document.getElementById("aimeat-app-ref");
+      if (!node) return null;
+      const ref = JSON.parse(node.textContent || "{}");
+      if (ref.owner && ref.app_id) return { owner: ref.owner, appId: ref.app_id };
+    } catch {
+    }
+    return null;
+  }
   try {
     const el = (
       /** @type {any} */
@@ -181,6 +221,12 @@
         webmcp.exposeNodeTools().catch(function() {
         });
       }, 0);
+    } else if (expose === "app") {
+      const ref = appRefFromPage(el);
+      if (ref) setTimeout(function() {
+        webmcp.exposeAppTools(ref).catch(function() {
+        });
+      }, 0);
     }
   } catch {
   }

package/dist/static/sdk-libs/exchange/browse.js

@@ -0,0 +1,81 @@
+/**
+ * @file exchange/browse.js
+ * @description The BROWSE half of AIMEAT.exchange — reading the market. Every call here maps to a
+ *   route the node publishes without authentication, so an app can render the catalogue, one
+ *   listing's full decision context, and its ODPS v4.1 descriptor to a signed-out visitor. The
+ *   session is sent when there is one (see client.js `maybe`) purely so a seller's own projections
+ *   are fresh; it changes what is CURRENT, never what is VISIBLE.
+ * @structure info() · list(filter) · search(q, filter) · get(id) · odps(id) · odpsYaml(id)
+ * @usage const { offerings } = await AIMEAT.exchange.list({ q: 'company', stats: true });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { pub, pubText, maybe, qs } from './client.js';
+
+const enc = encodeURIComponent;
+
+/**
+ * The marketplace's public economics: `{ rake_percent, rake_note, units, morsel_note }` — what the
+ * platform takes on each metered call, set by the node operator. Show it BEFORE a seller prices
+ * something, so the split is stated rather than discovered on the first sale.
+ * @returns {Promise<any>}
+ */
+export function info() {
+  return pub('/v1/exchange/info', 'Failed to read the EXCHANGE economics');
+}
+
+/**
+ * Browse listed offerings. Every supplied filter NARROWS, independently.
+ * @param {{ ext?: string, action?: string, q?: string, stats?: boolean }} [filter]
+ *   `q` free-text over title/description/coordinate/tags; `stats: true` folds each listing's usage
+ *   (contracts, calls, consumers, settled units, observed p50/p95) into the row.
+ * @returns {Promise<{ offerings: any[], count: number }>}
+ */
+export function list(filter) {
+  const f = filter || {};
+  const query = qs({ ext: f.ext, action: f.action, q: f.q, stats: f.stats ? '1' : null });
+  return maybe('/v1/exchange/offerings' + query, 'Failed to browse the marketplace');
+}
+
+/**
+ * Free-text search — the same route as {@link list}, named for what an app's search box does.
+ * @param {string} q
+ * @param {{ ext?: string, action?: string, stats?: boolean }} [filter]
+ * @returns {Promise<{ offerings: any[], count: number }>}
+ */
+export function search(q, filter) {
+  return list({ ...(filter || {}), q });
+}
+
+/**
+ * One offering in FULL: `{ offering, capability, call_recipe, stats, pacing, odps }` — the I/O
+ * schema, how to call it (the contract IS the access; no API key is issued), what it costs per call
+ * in morsels burned for pacing on top of the price, the observed usage, and a pointer to the ODPS
+ * document. One call, so an app need not stitch four.
+ * @param {string} id  Offering id (`off-…`).
+ * @returns {Promise<any>}
+ */
+export function get(id) {
+  return pub('/v1/exchange/offerings/' + enc(id), 'No such offering');
+}
+
+/**
+ * The offering as an Open Data Product Specification v4.1 document (JSON) — the interoperable
+ * descriptor an outside catalogue or a negotiating agent reads without knowing anything about
+ * AIMEAT. Derived on read, so it cannot drift from the listing it describes.
+ * @param {string} id
+ * @returns {Promise<{ odps_version: string, odps: any }>}
+ */
+export function odps(id) {
+  return pub('/v1/exchange/offerings/' + enc(id) + '/odps', 'No such offering');
+}
+
+/**
+ * The same ODPS v4.1 document in the spec's native YAML, as raw text — what you hand to a catalogue
+ * that expects the file, or show in a "copy this descriptor" box.
+ * @param {string} id
+ * @returns {Promise<string>}
+ */
+export function odpsYaml(id) {
+  return pubText('/v1/exchange/offerings/' + enc(id) + '/odps.yaml', 'No such offering');
+}

package/dist/static/sdk-libs/exchange/client.js

@@ -0,0 +1,131 @@
+/**
+ * @file exchange/client.js
+ * @description Shared fetch plumbing for the aimeat-exchange library. EXCHANGE is a two-sided market
+ *   whose read surface is deliberately PUBLIC (browsing a listing, its ODPS document and its stats
+ *   needs no account) while every write and every "mine" read is authorised. So there are three call
+ *   shapes rather than one: `pub` (never sends a session), `authed` (requires one — the auth guard
+ *   names this library in its error) and `maybe` (sends the session when there is one). `maybe` is not
+ *   a convenience: GET /v1/exchange/offerings reconciles the CALLER's own projections before it
+ *   answers, so a signed-in seller browsing the market sees their own listings up to date, and a
+ *   signed-out visitor still gets the market.
+ *   SECURITY: this file carries no credentials of its own. It sends the aimeat-auth session and
+ *   renders what comes back — who may see what is the server's decision, never this library's.
+ * @structure exchangeError(res, fallback) · qs(params) · pub(path) · authed(path, opts) ·
+ *   maybe(path) · hasSession()
+ * @usage import { authed, pub, qs, exchangeError } from './client.js';
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { APEX_URL } from '../_core/config.js';
+import { makeSession } from '../_core/session.js';
+
+const NODE_URL = APEX_URL;
+const { authFetch } = makeSession('aimeat-exchange.js');
+
+/**
+ * Build an Error from a failed envelope, preserving the machine-readable code so callers can branch
+ * on it (`SOURCE_MANAGED`, `SCHEMA_REQUIRED`, `USAGE_TERMS_REQUIRED`, `NOT_PRICED`, `BUDGET_TOO_LOW`
+ * …) instead of matching on message text. EXCHANGE refusals are mostly *actionable* — they say which
+ * field the provider must publish — so the message is kept verbatim.
+ * @param {any} res            The parsed envelope.
+ * @param {string} fallback    Message to use when the envelope carries none.
+ * @returns {Error & { code?: string, details?: unknown }}
+ */
+export function exchangeError(res, fallback) {
+  const e = /** @type {Error & { code?: string, details?: unknown }} */ (
+    new Error((res && res.error && res.error.message) || fallback));
+  e.code = res && res.error && res.error.code;
+  e.details = res && res.error && res.error.details;
+  return e;
+}
+
+/**
+ * Serialise a query object, dropping null/undefined/'' so an unset filter is not sent as an empty
+ * one (the offerings route treats every supplied filter as a NARROWING term).
+ * @param {Record<string, string|number|boolean|null|undefined>} [params]
+ * @returns {string}  `?a=1&b=2`, or '' when nothing is set.
+ */
+export function qs(params) {
+  const parts = [];
+  for (const k of Object.keys(params || {})) {
+    const v = params[k];
+    if (v === null || v === undefined || v === '') continue;
+    parts.push(encodeURIComponent(k) + '=' + encodeURIComponent(String(v)));
+  }
+  return parts.length ? '?' + parts.join('&') : '';
+}
+
+/** True when aimeat-auth is loaded AND someone is signed in — never throws. */
+export function hasSession() {
+  try {
+    const auth = window.AIMEAT && window.AIMEAT.auth;
+    return !!(auth && auth.getSession());
+  } catch { return false; }
+}
+
+/**
+ * A PUBLIC read — no session, ever. Used for the browse surface so a signed-out visitor sees the
+ * market exactly as the node publishes it.
+ * @param {string} path
+ * @param {string} fallback  Error message when the envelope carries none.
+ * @returns {Promise<any>}   The envelope's `data`.
+ */
+export async function pub(path, fallback) {
+  const r = await fetch(NODE_URL + path);
+  const res = await r.json();
+  if (!res.ok) throw exchangeError(res, fallback);
+  return res.data;
+}
+
+/** A PUBLIC read that returns raw text rather than an envelope (the ODPS `.yaml` projection). */
+export async function pubText(path, fallback) {
+  const r = await fetch(NODE_URL + path);
+  const text = await r.text();
+  if (!r.ok) {
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* a non-envelope error body — fall through */ }
+    throw exchangeError(parsed, fallback);
+  }
+  return text;
+}
+
+/**
+ * An AUTHORISED call — the session's own fetch (bearer token, refresh on 401, scope self-heal).
+ * @param {string} path
+ * @param {RequestInit} [opts]
+ * @param {string} [fallback]
+ * @returns {Promise<any>}  The envelope's `data`.
+ */
+export async function authed(path, opts, fallback) {
+  const res = await authFetch(path, opts);
+  if (!res.ok) throw exchangeError(res, fallback || 'EXCHANGE request failed');
+  return res.data;
+}
+
+/**
+ * A public read that SENDS the session when there is one. Signed in, the offerings route brings the
+ * caller's own projections up to date before answering; signed out, the same call still returns the
+ * public market.
+ * @param {string} path
+ * @param {string} fallback
+ * @returns {Promise<any>}
+ */
+export async function maybe(path, fallback) {
+  if (!hasSession()) return pub(path, fallback);
+  try {
+    return await authed(path, undefined, fallback);
+  } catch (e) {
+    // A stale or scope-short session must never turn a PUBLIC surface into an error page.
+    if (e && (e.code === 'UNAUTHORIZED' || e.code === 'FORBIDDEN')) return pub(path, fallback);
+    throw e;
+  }
+}
+
+/** POST/DELETE helper: JSON body, authorised. */
+export function send(path, method, body, fallback) {
+  const opts = /** @type {RequestInit} */ ({ method });
+  if (body !== undefined) opts.body = JSON.stringify(body);
+  return authed(path, opts, fallback);
+}
+
+export { NODE_URL };

package/dist/static/sdk-libs/exchange/contracts.js

@@ -0,0 +1,228 @@
+/**
+ * @file exchange/contracts.js
+ * @description The BUY half of AIMEAT.exchange — accepting a contract, seeing what it has consumed,
+ *   turning it off, renegotiating it, and (for agent-work) starting and receiving a task.
+ *
+ *   A contract here is a metered entitlement: the consumer chooses only their BUDGET, the per-call
+ *   price is read authoritatively from the provider. That is why `accept` takes an offering id and a
+ *   cap rather than a price — a price sent from a browser would be a price a buyer set for a seller.
+ * @structure contracts() · accept(offeringId, opts) · off(contract, opts) · history() · spend() ·
+ *   proposals() · propose(spec) · acceptProposal/declineProposal/withdrawProposal ·
+ *   startWork(spec) · deliverWork(id, spec) · work(opts) · coordinateOf
+ * @usage const c = await AIMEAT.exchange.accept('off-abc123', { capUnits: 500 });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { authed, send, qs, exchangeError } from './client.js';
+import { get as getOffering } from './browse.js';
+
+const enc = encodeURIComponent;
+
+function compact(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) if (obj[k] !== undefined) out[k] = obj[k];
+  return out;
+}
+function pick(...vals) {
+  for (const v of vals) if (v !== undefined && v !== null) return v;
+  return undefined;
+}
+
+/**
+ * Every contract the caller's OWNER holds, with what each has consumed: budget cap, spent, calls
+ * remaining, the pricing model, the pacing toll it was signed at, the rake, and `callers` — which
+ * of the owner's principals ran it up.
+ * @returns {Promise<{ entitlements: any[] }>}
+ */
+export function contracts() {
+  return authed('/v1/exchange/entitlements', undefined, 'Failed to read your contracts');
+}
+
+/**
+ * Accept a contract for a listed offering → mint the durable entitlement the metered gateway then
+ * honours on every call. You choose the budget; the provider's price is authoritative.
+ * @param {string} offeringId
+ * @param {{ capUnits?: number|null, appId?: string, planId?: string, contractRef?: string,
+ *           escrowParty?: 'consumer'|'provider' }} [opts]
+ *   `capUnits` is YOUR spend ceiling in the offering's unit (money micro-units or morsels); omit for
+ *   uncapped. Below one charge it is refused with `BUDGET_TOO_LOW` rather than minted unusable.
+ *   `planId` picks a provider-declared bundle/subscription plan.
+ * @returns {Promise<any>}  The minted contract.
+ */
+export async function accept(offeringId, opts) {
+  const o = /** @type {Record<string, any>} */ (opts || {});
+  const d = await send('/v1/exchange/entitlements', 'POST', compact({
+    offering_id: offeringId,
+    cap_units: pick(o.capUnits, o.cap_units),
+    app_id: pick(o.appId, o.app_id),
+    plan_id: pick(o.planId, o.plan_id),
+    contract_ref: pick(o.contractRef, o.contract_ref),
+    escrow_party: pick(o.escrowParty, o.escrow_party),
+  }), 'Failed to accept the contract');
+  return d.entitlement;
+}
+
+/**
+ * Resolve whatever an app is holding — a contract row, an offering detail, an offering id, or a
+ * plain `{ ext, action }` — into the metered coordinate the off-switch and proposals key on.
+ * @param {any} contract
+ * @returns {Promise<{ ext: string, action: string }>}
+ */
+export async function coordinateOf(contract) {
+  if (typeof contract === 'string') {
+    // An offering id (`off-…`); anything else cannot be resolved without a coordinate.
+    const d = await getOffering(contract);
+    return { ext: d.offering.ext, action: d.offering.action };
+  }
+  const c = contract || {};
+  const ext = c.ext || (c.offering && c.offering.ext);
+  const action = c.action || (c.offering && c.offering.action);
+  if (!ext || !action) {
+    throw exchangeError({ error: { code: 'BAD_REQUEST', message:
+      'Name the contract by its capability coordinate ({ ext, action }), a contract row from contracts(), or an offering id.' } },
+    'Unresolvable contract reference');
+  }
+  return { ext, action };
+}
+
+/**
+ * The consumer's OFF-SWITCH. `pause` is reversible (re-accepting resumes it and carries the spend
+ * forward); `revoke` is terminal. Only the contract's own consumer may.
+ * @param {any} contract  A contract row, an offering id, or `{ ext, action }`.
+ * @param {{ mode?: 'pause'|'revoke' }} [opts]  Default `pause`.
+ * @returns {Promise<any>}
+ */
+export async function off(contract, opts) {
+  const { ext, action } = await coordinateOf(contract);
+  return send('/v1/exchange/entitlements/off', 'POST', {
+    ext, action, mode: (opts && opts.mode) === 'revoke' ? 'revoke' : 'pause',
+  }, 'Failed to switch the contract off');
+}
+
+/**
+ * Your PAST (archived / superseded) contracts as a CONSUMER — the terms a renegotiation replaced.
+ * @returns {Promise<{ history: any[], count: number }>}
+ */
+export function history() {
+  return authed('/v1/exchange/entitlements/history', undefined, 'Failed to read your contract history');
+}
+
+/**
+ * What you have spent OUTBOUND, per provider and per unit. DERIVED, not a server endpoint: the node
+ * aggregates the SELLER's side (offering stats, consumer lineage, earnings) and exposes the buyer's
+ * side only per app (`GET /v1/apps/cost?app_id=…`), so this folds the caller's own contracts — the
+ * same records the per-app view reads — into one figure. It therefore counts exactly what the
+ * caller's OWNER holds a contract for, and nothing about another of their accounts.
+ * @returns {Promise<{ byProvider: any[], byUnit: Record<string, { spentUnits: number, calls: number, contracts: number }>,
+ *                     totalCalls: number, totalContracts: number }>}
+ */
+export async function spend() {
+  const { entitlements } = await contracts();
+  const byUnit = /** @type {Record<string, { spentUnits: number, calls: number, contracts: number }>} */ ({});
+  const providers = /** @type {Record<string, any>} */ ({});
+  let totalCalls = 0;
+  for (const e of entitlements || []) {
+    const rail = e.unit === 'money' ? (e.currency || 'EUR') : 'morsels';
+    const u = byUnit[rail] || (byUnit[rail] = { spentUnits: 0, calls: 0, contracts: 0 });
+    u.spentUnits += e.budget ? e.budget.spent_units : 0;
+    u.calls += e.budget ? e.budget.calls : 0;
+    u.contracts += 1;
+    totalCalls += e.budget ? e.budget.calls : 0;
+
+    const key = e.provider + '|' + rail;
+    const p = providers[key] || (providers[key] = {
+      provider: e.provider, unit: rail, spentUnits: 0, calls: 0, contracts: 0, capabilities: [],
+    });
+    p.spentUnits += e.budget ? e.budget.spent_units : 0;
+    p.calls += e.budget ? e.budget.calls : 0;
+    p.contracts += 1;
+    if (p.capabilities.indexOf(e.capability) === -1) p.capabilities.push(e.capability);
+  }
+  const byProvider = Object.keys(providers).map(k => providers[k])
+    .sort((a, b) => b.spentUnits - a.spentUnits);
+  return { byProvider, byUnit, totalCalls, totalContracts: (entitlements || []).length };
+}
+
+// ── Renegotiation ────────────────────────────────────────────────────────────
+
+/**
+ * Every contract-change proposal you are party to (incoming and outgoing).
+ * @returns {Promise<{ proposals: any[], count: number }>}
+ */
+export function proposals() {
+  return authed('/v1/exchange/proposals', undefined, 'Failed to read proposals');
+}
+
+/**
+ * Propose new terms on a live contract. Either party may: a consumer renegotiates their own, a
+ * provider renegotiates a named consumer's (`consumerGaii`). Nothing changes until the counterparty
+ * accepts; they are notified in Profile > Messages.
+ * @param {{ ext?: string, action?: string, contract?: any, consumerGaii?: string,
+ *           newPricePerCall?: number, newCapUnits?: number, note?: string }} spec
+ * @returns {Promise<any>}  The pending proposal.
+ */
+export async function propose(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const { ext, action } = await coordinateOf(s.contract || { ext: s.ext, action: s.action });
+  const d = await send('/v1/exchange/proposals', 'POST', compact({
+    ext, action,
+    consumer_gaii: pick(s.consumerGaii, s.consumer_gaii),
+    new_price_per_call: pick(s.newPricePerCall, s.new_price_per_call),
+    new_cap_units: pick(s.newCapUnits, s.new_cap_units),
+    note: s.note,
+  }), 'Failed to propose new terms');
+  return d.proposal;
+}
+
+/** The COUNTERPARTY accepts → the old contract is archived and a new one minted at the new terms. */
+export function acceptProposal(id) {
+  return send('/v1/exchange/proposals/' + enc(id) + '/accept', 'POST', {}, 'Failed to accept the proposal');
+}
+/** The counterparty declines — the contract is unchanged. */
+export function declineProposal(id) {
+  return send('/v1/exchange/proposals/' + enc(id) + '/decline', 'POST', {}, 'Failed to decline the proposal');
+}
+/** The PROPOSER withdraws their own pending proposal. */
+export function withdrawProposal(id) {
+  return send('/v1/exchange/proposals/' + enc(id) + '/withdraw', 'POST', {}, 'Failed to withdraw the proposal');
+}
+
+// ── Agent work (the async surface — settled per delivered task) ───────────────
+
+/**
+ * Start a task under an agent-work contract. Nothing is charged yet: the per-task price is metered
+ * when the provider DELIVERS. Without an active contract this is refused with `NO_CONTRACT` (402).
+ * @param {{ offeringId: string, input?: any, note?: string }} spec
+ * @returns {Promise<any>}  The open work item.
+ */
+export async function startWork(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const d = await send('/v1/exchange/work', 'POST', compact({
+    offering_id: pick(s.offeringId, s.offering_id), input: s.input, note: s.note,
+  }), 'Failed to start the work');
+  return d.work;
+}
+
+/**
+ * Deliver a task you were commissioned for → settle on delivery (the consumer is charged, you are
+ * credited its cut, the rake routed, the budget decremented).
+ * @param {string} id
+ * @param {{ output?: any, note?: string }} [spec]
+ * @returns {Promise<any>}  The delivered work item.
+ */
+export async function deliverWork(id, spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const d = await send('/v1/exchange/work/' + enc(id) + '/deliver', 'POST',
+    compact({ output: s.output, note: s.note }), 'Failed to deliver the work');
+  return d.work;
+}
+
+/**
+ * Your agent-work items. `{ role: 'provider' }` for work commissioned FROM you; default is work you
+ * commissioned.
+ * @param {{ role?: 'consumer'|'provider' }} [opts]
+ * @returns {Promise<{ work: any[], count: number, role: string }>}
+ */
+export function work(opts) {
+  return authed('/v1/exchange/work' + qs({ role: opts && opts.role }), undefined, 'Failed to read your work items');
+}

package/dist/static/sdk-libs/exchange/demand.js

@@ -0,0 +1,106 @@
+/**
+ * @file exchange/demand.js
+ * @description The DEMAND side of AIMEAT.exchange — an app says what it needs and cannot produce
+ *   itself, providers bid, the requester accepts one and a contract is minted. A need is always
+ *   posted on behalf of a specific app (`appId`), which is what turns a wish into a request a
+ *   provider can judge: they can see who they would be serving before offering.
+ * @structure needs(opts) · postNeed(spec) · closeNeed(id) · bids(needId) · bid(needId, spec) ·
+ *   acceptBid(needId, bidId, opts)
+ * @usage await AIMEAT.exchange.postNeed({ appId: 'alice/crm', description: '…', spec: { requiredFields: [...] } });
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { authed, pub, send, qs } from './client.js';
+
+const enc = encodeURIComponent;
+
+function compact(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) if (obj[k] !== undefined) out[k] = obj[k];
+  return out;
+}
+function pick(...vals) {
+  for (const v of vals) if (v !== undefined && v !== null) return v;
+  return undefined;
+}
+
+/**
+ * Browse needs. Public. Each is enriched with `appContext` — the requesting app's published name
+ * and description — so a provider judges the consumer, not just the ask.
+ * @param {{ open?: boolean, mine?: boolean }} [opts]  `mine` requires a session.
+ * @returns {Promise<{ needs: any[], count: number }>}
+ */
+export function needs(opts) {
+  const o = opts || {};
+  const query = qs({ open: o.open ? '1' : null, mine: o.mine ? '1' : null });
+  return o.mine
+    ? authed('/v1/exchange/needs' + query, undefined, 'Failed to read your needs')
+    : pub('/v1/exchange/needs' + query, 'Failed to browse needs');
+}
+
+/**
+ * Post an open need. `appId` is REQUIRED (`NEED_APP_REQUIRED` without it) — a need belongs to the
+ * app that will call the answer. The response carries `matches`: offerings that already satisfy it,
+ * so the requester can accept one directly instead of waiting for a bid.
+ * @param {{ appId: string, description: string, ext?: string, action?: string,
+ *           spec?: { requiredFields?: string[], format?: string, sample?: string, notes?: string,
+ *                    inputSchema?: object, outputSchema?: object },
+ *           usageIntent?: string, budgetUnit?: 'money'|'morsels', budgetCap?: number,
+ *           autonomy?: 'supervised'|'auto' }} spec
+ * @returns {Promise<{ need: any, matches: any[] }>}
+ */
+export function postNeed(spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  return send('/v1/exchange/needs', 'POST', compact({
+    app_id: pick(s.appId, s.app_id),
+    description: s.description,
+    ext: s.ext,
+    action: s.action,
+    spec: s.spec,
+    usage_intent: pick(s.usageIntent, s.usage_intent),
+    budget_unit: pick(s.budgetUnit, s.budget_unit),
+    budget_cap: pick(s.budgetCap, s.budget_cap),
+    autonomy: s.autonomy,
+  }), 'Failed to post the need');
+}
+
+/** Close one of your own needs. */
+export function closeNeed(id) {
+  return send('/v1/exchange/needs/' + enc(id) + '/close', 'POST', {}, 'Failed to close the need');
+}
+
+/** The bids on a need. Public — demand and the answers to it are both browsable. */
+export function bids(needId) {
+  return pub('/v1/exchange/needs/' + enc(needId) + '/bids', 'Failed to read bids');
+}
+
+/**
+ * Bid on an open need with an action YOUR extension owns (anything else is refused, 403).
+ * @param {string} needId
+ * @param {{ ext: string, action: string, offeringId?: string, planId?: string, note?: string }} spec
+ * @returns {Promise<any>}  The open bid.
+ */
+export async function bid(needId, spec) {
+  const s = /** @type {Record<string, any>} */ (spec || {});
+  const d = await send('/v1/exchange/needs/' + enc(needId) + '/bids', 'POST', compact({
+    ext: s.ext, action: s.action,
+    offering_id: pick(s.offeringId, s.offering_id),
+    plan_id: pick(s.planId, s.plan_id),
+    note: s.note,
+  }), 'Failed to place the bid');
+  return d.bid;
+}
+
+/**
+ * The REQUESTER accepts a bid → the entitlement is minted (consumer = requester, provider = bidder)
+ * at the provider's authoritative price, and the need is marked matched.
+ * @param {string} needId
+ * @param {string} bidId
+ * @param {{ capUnits?: number }} [opts]  Defaults to the need's own budget cap.
+ * @returns {Promise<any>}
+ */
+export function acceptBid(needId, bidId, opts) {
+  const o = /** @type {Record<string, any>} */ (opts || {});
+  return send('/v1/exchange/needs/' + enc(needId) + '/bids/' + enc(bidId) + '/accept', 'POST',
+    compact({ cap_units: pick(o.capUnits, o.cap_units) }), 'Failed to accept the bid');
+}

package/dist/static/sdk-libs/exchange/earnings.js

@@ -0,0 +1,39 @@
+/**
+ * @file exchange/earnings.js
+ * @description What the market OWES the caller. A money-priced metered call settles through the
+ *   accrual rail: no per-call payment-processor charge and no custodial escrow — each call books the
+ *   seller's net (price minus the platform rake) as a `pending` payable. This reads that book.
+ *
+ *   What it deliberately is NOT: a payout, an invoice, or a way to mark something settled. The
+ *   figure is made READABLE here; moving money is a later phase, and a browser library that implied
+ *   otherwise would be making a promise about money that nothing behind it keeps.
+ *
+ *   SECURITY: no payment credentials pass through here in either direction. A seller's PSP
+ *   configuration is server-side and never readable; this call returns amounts and buyers, nothing
+ *   that could be used to charge anyone.
+ * @structure earnings(opts)
+ * @usage const e = await AIMEAT.exchange.earnings();  // e.currencies.EUR.pending
+ * @version-history
+ *   v1.0.0 — 2026-07-28 — Initial (NOSTE prompt 02 — the EXCHANGE browser library, gap G19).
+ */
+import { authed, qs } from './client.js';
+
+/**
+ * The caller's own accrued earnings, per currency, with the per-entry breakdown behind the figure.
+ *
+ * Returns `{ seller, currencies: { EUR: { pending, settled, total, entries } }, entries: [{
+ * tracking_code, amount, currency, method, status, at, reference, buyer }], count, note }`.
+ * Amounts are NET of the platform rake, in the currency's integer micro-units — format them with
+ * {@link module:exchange/format.fmtUnit}, never by dividing by hand.
+ *
+ * `pending` means booked as owed and not yet paid out. Owner-scoped by the server on the money
+ * identity, so an owner's agent or a granted app reads the OWNER's earnings and never another
+ * seller's; a non-owner principal needs the `wallet:read` scope.
+ * @param {{ status?: 'pending'|'settled', currency?: string, limit?: number }} [opts]
+ * @returns {Promise<any>}
+ */
+export function earnings(opts) {
+  const o = opts || {};
+  return authed('/v1/exchange/earnings' + qs({ status: o.status, currency: o.currency, limit: o.limit }),
+    undefined, 'Failed to read your earnings');
+}