@crossly/mcp 0.0.0-stage → 0.2.0

package/dist/tools/cosm.js

@@ -0,0 +1,75 @@
+import { cosmAttestations } from './cosm/attestations.js';
+import { cosmAuction } from './cosm/auction.js';
+import { cosmCosmetics } from './cosm/cosmetics.js';
+import { cosmDesigner } from './cosm/designer.js';
+import { cosmFusionHandles } from './cosm/fusion-handles.js';
+import { cosmPegs } from './cosm/pegs.js';
+import { cosmStorefront } from './cosm/storefront.js';
+import { cosmSupply } from './cosm/supply.js';
+import { cosmWithdrawals } from './cosm/withdrawals.js';
+/**
+ * COSM — the metaverse cosmetics currency.
+ *
+ * ── DO NOT CONFUSE IT WITH CBX ────────────────────────────────────────
+ * They are opposites, and describing one with the other's properties is
+ * the most likely way an agent misleads somebody here:
+ *
+ *   CBX   fixed supply · backed by a reserve · spends RECIRCULATE
+ *         · withdrawable once matured
+ *   COSM  minted on demand · backed by NOTHING · spends BURN
+ *         · not withdrawable at all yet
+ *
+ * ── AMOUNTS ARE STRINGS OF BASE UNITS WITH SIX DECIMALS ───────────────
+ * `"10000000000"` is ten thousand COSM. They are strings because a JSON
+ * number loses precision past 2^53 — about nine billion COSM. Never do
+ * float arithmetic on them, and divide by 1e6 before showing a figure to
+ * a person.
+ *
+ * ── WHAT AN AGENT MUST NOT MISREPRESENT ───────────────────────────────
+ * COSM IS NOT WITHDRAWABLE AND IS NOT A YIELD. It is earned by ACTIVITY
+ * — accepting CBX on a sale, selling, buying goods — and staking only
+ * multiplies the RATE. There is no entitlement without activity, however
+ * large a stake. If somebody asks whether they can stake COSM or CBX to
+ * earn COSM passively, the answer is no, and that is deliberate rather
+ * than a missing feature.
+ *
+ * THERE IS NO WAY TO CASH IT OUT TODAY. The withdrawal tools exist and
+ * they REFUSE — `request_cosm_withdrawal` returns a 409 listing what is
+ * outstanding. Call `get_cosm_withdrawals` and read `meta.open` before
+ * offering it to anybody; do not call the request tool to discover that
+ * it is closed.
+ *
+ * Do not tell anybody a market is coming on a date. It is gated on an
+ * audited minter, a securities opinion, a money-transmission review and
+ * the emission invariant proven under real volume, and NONE of those has
+ * a timetable. "Not yet, and here is what has to happen first" is the
+ * honest answer; a guessed quarter is not.
+ *
+ * A USER-TO-USER SEND DOES NOT EXIST AT ANY SETTING. If somebody asks to
+ * send COSM to another user or to an address, that is not a thing this
+ * API can do. The auction house moves COSM between users but only
+ * through a matched listing for amounts derived from it.
+ *
+ * THE TIERS ARE DISJOINT. `premium` cosmetics cost CASH only, `earned`
+ * cost COSM only, `stake_exclusive` cannot be bought at any price in any
+ * currency. Never imply a premium item can be earned or that a
+ * stake-exclusive one can be purchased.
+ *
+ * ── SPENDING COSM DESTROYS IT ─────────────────────────────────────────
+ * Buying an earned cosmetic, a fusion cost and the auction fee all BURN.
+ * Nothing is credited to Crossly. If a user asks where their COSM went,
+ * the honest answer is that it no longer exists — that is what makes the
+ * supply figures meaningful.
+ */
+export const cosmTools = [
+    ...cosmSupply,
+    ...cosmCosmetics,
+    ...cosmAuction,
+    ...cosmFusionHandles,
+    ...cosmWithdrawals,
+    ...cosmAttestations,
+    ...cosmPegs,
+    ...cosmStorefront,
+    ...cosmDesigner,
+];
+//# sourceMappingURL=cosm.js.map

package/dist/tools/cosm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cosm.js","sourceRoot":"","sources":["../../src/tools/cosm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,CAAC,MAAM,SAAS,GAAc;IAClC,GAAG,UAAU;IACb,GAAG,aAAa;IAChB,GAAG,WAAW;IACd,GAAG,iBAAiB;IACpB,GAAG,eAAe;IAClB,GAAG,gBAAgB;IACnB,GAAG,QAAQ;IACX,GAAG,cAAc;IACjB,GAAG,YAAY;CAChB,CAAC"}

package/dist/tools/customers.d.ts

@@ -0,0 +1,3 @@
+import { ToolDef } from './types.js';
+export declare const customersTools: ToolDef[];
+//# sourceMappingURL=customers.d.ts.map

package/dist/tools/customers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customers.d.ts","sourceRoot":"","sources":["../../src/tools/customers.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,OAAO,EAAE,MAAM,YAAY,CAAC;AAEvD,eAAO,MAAM,cAAc,EAAE,OAAO,EA8JnC,CAAC"}

package/dist/tools/customers.js

@@ -0,0 +1,147 @@
+import { apiGet, apiPost } from '../api.js';
+import { IDEMPOTENCY_PROP } from './types.js';
+export const customersTools = [
+    {
+        name: 'list_customers',
+        description: "Aggregated customer view — groups the seller's orders by lower(buyer_username) so the same buyer " +
+            'on multiple platforms shows as one row. Returns normalizedHandle, platforms[], totalOrders, totalSpent, ' +
+            'lastOrderAt, firstOrderAt, plus avatarUrl, displayName and bestRating ({value 0-5, count, platform} or null) ' +
+            'from their marketplace buyer profiles. Sorted by totalOrders DESC then totalSpent DESC — repeat buyers first.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                search: {
+                    type: 'string',
+                    description: 'Case-insensitive substring match on buyer username. Omit to list everyone.',
+                },
+                page: {
+                    type: 'integer',
+                    minimum: 1,
+                    default: 1,
+                    description: '1-indexed page of the aggregated customer list (offset = (page-1)*limit). Default 1. Rows are ' +
+                        'aggregated buyers, not orders.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 100,
+                    default: 25,
+                    description: 'Customers per page. Default 25; the server clamps anything above 100 down to 100 rather than ' +
+                        'erroring.',
+                },
+            },
+            additionalProperties: false,
+        },
+        handler: (args) => apiGet('/v1/customers', {
+            search: args.search,
+            page: args.page,
+            limit: args.limit,
+        }),
+    },
+    {
+        name: 'get_customer',
+        description: 'Fetch one buyer (by normalized handle) plus their recent 50 orders across all platforms. ' +
+            'Use this to look up a repeat buyer before sending a message or to investigate a dispute history. ' +
+            'Also returns `contact` — email, name, phone and the most recent shipping address, each resolved ' +
+            'from the latest order that carried it. Fields are null when the marketplace does not share them ' +
+            'with sellers, which is most of them; eBay is the one that reliably does. ' +
+            'Also returns `profiles` — one per platform the buyer ordered on: displayName, avatarUrl, profileUrl, ' +
+            'rating/ratingCount (0-5 stars where the marketplace has them), feedbackScore, positivePercent, memberSince, ' +
+            'location, verified, badges, plus source (order | profile_fetch | crossly) and fetchStatus (ok | unsupported | ' +
+            'not_found | error); null fields mean the marketplace did not share them. And `stats` over ALL of their ' +
+            'orders (not just the 50 shown): totalOrders, totalSpent, avgOrderValue, first/lastOrderAt, ' +
+            'daysSinceLastOrder, platformsCount, cancelledCount, returnsCount, disputesCount, messagesCount, ' +
+            'offersCount, repeatBuyer.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handle: {
+                    type: 'string',
+                    description: 'Normalized (lowercase) buyer handle from list_customers.',
+                },
+            },
+            required: ['handle'],
+            additionalProperties: false,
+        },
+        handler: (args) => apiGet(`/v1/customers/${encodeURIComponent(args.handle.toLowerCase())}`),
+    },
+    {
+        name: 'refresh_customer_profile',
+        description: "Re-read a buyer's marketplace profiles now (avatar, rating, feedback, member-since) on every platform they " +
+            'ordered on, skipping the 7-day freshness window. Asynchronous: returns which platforms were queued; call ' +
+            'get_customer a little later to see the refreshed `profiles`. Platforms with no readable profile still ' +
+            'refresh what their orders carry. Rate-limited per seller (10/minute). Pass an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handle: {
+                    type: 'string',
+                    description: 'Normalized (lowercase) buyer handle from list_customers.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['handle'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, handle } = args;
+            return apiPost(`/v1/customers/${encodeURIComponent(handle.toLowerCase())}/refresh-profile`, {}, idempotencyKey);
+        },
+    },
+    {
+        name: 'customers_bulk_delete',
+        description: "Bulk-blocklist customer handles. Customers aren't a CRUD table — they aggregate from orders — so 'delete' means " +
+            "'hide this handle from the customers view and stop future aggregation'. Existing orders rows are untouched. Pass " +
+            'an idempotencyKey on retries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handles: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 1,
+                    maxItems: 500,
+                    description: 'Buyer handles to blocklist — the `normalizedHandle` values from list_customers. 1-500 per call, ' +
+                        'each 1-200 characters. Lowercased server-side, so casing does not matter, and the same handle is ' +
+                        'blocklisted across every platform it traded on (that is what "normalized" means here). Re-sending ' +
+                        'an already-blocklisted handle is a no-op, not an error. Existing orders rows are never touched.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['handles'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/customers/bulk-delete', body, idempotencyKey);
+        },
+    },
+    {
+        name: 'customers_bulk_export',
+        description: 'Export aggregated customer rows for a list of handles as CSV. Returns the CSV text body — caller should treat as a string. ' +
+            'Pass an idempotencyKey for cache-replay safety.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                handles: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 1,
+                    maxItems: 2000,
+                    description: 'Buyer handles to export — `normalizedHandle` values from list_customers. 1-2000 per call, each ' +
+                        '1-200 characters; lowercased server-side. Output columns are handle, platforms (pipe-separated), ' +
+                        'total_orders, total_spent, last_order, first_order. Handles with no matching order are simply ' +
+                        'absent from the CSV rather than an error, so a short file means unmatched handles, not a failure.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['handles'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/customers/bulk-export', body, idempotencyKey);
+        },
+    },
+];
+//# sourceMappingURL=customers.js.map

package/dist/tools/customers.js.map

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

package/dist/tools/dao.d.ts

@@ -0,0 +1,53 @@
+import { ToolDef } from './types.js';
+/**
+ * The Crossly DAO — staked CBX decides what the events pool funds.
+ *
+ * ── THE ONE RULE AN AGENT MUST NOT HELP ANYBODY AROUND ────────────────
+ * A VOTE CAN NEVER DIRECT FUNDS TO THE VOTERS. `beneficiaryKind` is a
+ * closed set — community_event, grant, charity, marketing, policy — with
+ * no stakers, no holders, no airdrop and no distribution option, in this
+ * schema, in the route, in the service and in a database CHECK.
+ *
+ * If somebody asks for a proposal that pays out to holders, to stakers,
+ * to "the community" as a balance credit, or to themselves, the answer is
+ * that this mechanism cannot express it. Do not reach for `grant` with
+ * the electorate as the grantee, or `community_event` for an event whose
+ * benefit is a token distribution — that is the same thing wearing a
+ * different label, and a distribution decided by its own recipients is a
+ * dividend whatever it is called. THE DAO DECIDES WHAT TO FUND, NEVER WHO
+ * GETS PAID.
+ *
+ * ── NO TOOL HERE MOVES MONEY, AND THAT IS NOT AN OVERSIGHT ────────────
+ * A passed proposal sets a STATUS. Disbursing goes through a campaign
+ * with a preview and a human approval, and there is no execute or
+ * disburse endpoint on this surface at all. Never tell somebody a passed
+ * proposal has been funded — it has been AUTHORISED.
+ *
+ * ── VOTING POWER IS FROZEN AT OPEN ────────────────────────────────────
+ * Weight is staked size x tenure, snapshotted when the proposal opens.
+ * Staking after seeing a proposal grants NO vote on it, and the quorum
+ * denominator never recomputes. If somebody asks how to acquire weight
+ * for a live vote, there is no way: that is the acquire-vote-sell attack
+ * and closing it is the point.
+ *
+ * Any single voter is capped at 10% of total weight however much they
+ * hold. Note the direction — the cap is on WEIGHT, not on who may
+ * propose. Proposing is open above a small stake threshold on purpose:
+ * restricting proposals to large holders is the intuitive whale defence
+ * and the wrong one, because it hands the agenda to exactly the
+ * concentration it was meant to contain.
+ *
+ * ── PARTICIPATION IS NOT A YIELD ──────────────────────────────────────
+ * Voting earns nothing. Proposing earns nothing. Staking multiplies a
+ * COSM earn RATE on activity and grants governance weight; it pays no
+ * return on the stake itself. If somebody is weighing a stake as an
+ * investment, that framing is wrong and worth correcting.
+ *
+ * ── AMOUNTS ARE STRINGS OF BASE UNITS ─────────────────────────────────
+ * `requestedBaseUnits` and every power figure are strings, because a
+ * JSON number loses precision past 2^53. Never do float arithmetic on
+ * them. CBX decimals are per-merchant config, so read them from the CBX
+ * config rather than assuming a count before converting for display.
+ */
+export declare const daoTools: ToolDef[];
+//# sourceMappingURL=dao.d.ts.map

package/dist/tools/dao.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dao.d.ts","sourceRoot":"","sources":["../../src/tools/dao.ts"],"names":[],"mappings":"AACA,OAAO,EAAoB,OAAO,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,EAmV7B,CAAC"}

package/dist/tools/dao.js

@@ -0,0 +1,351 @@
+import { apiDelete, apiGet, apiPost } from '../api.js';
+import { IDEMPOTENCY_PROP } from './types.js';
+/**
+ * The Crossly DAO — staked CBX decides what the events pool funds.
+ *
+ * ── THE ONE RULE AN AGENT MUST NOT HELP ANYBODY AROUND ────────────────
+ * A VOTE CAN NEVER DIRECT FUNDS TO THE VOTERS. `beneficiaryKind` is a
+ * closed set — community_event, grant, charity, marketing, policy — with
+ * no stakers, no holders, no airdrop and no distribution option, in this
+ * schema, in the route, in the service and in a database CHECK.
+ *
+ * If somebody asks for a proposal that pays out to holders, to stakers,
+ * to "the community" as a balance credit, or to themselves, the answer is
+ * that this mechanism cannot express it. Do not reach for `grant` with
+ * the electorate as the grantee, or `community_event` for an event whose
+ * benefit is a token distribution — that is the same thing wearing a
+ * different label, and a distribution decided by its own recipients is a
+ * dividend whatever it is called. THE DAO DECIDES WHAT TO FUND, NEVER WHO
+ * GETS PAID.
+ *
+ * ── NO TOOL HERE MOVES MONEY, AND THAT IS NOT AN OVERSIGHT ────────────
+ * A passed proposal sets a STATUS. Disbursing goes through a campaign
+ * with a preview and a human approval, and there is no execute or
+ * disburse endpoint on this surface at all. Never tell somebody a passed
+ * proposal has been funded — it has been AUTHORISED.
+ *
+ * ── VOTING POWER IS FROZEN AT OPEN ────────────────────────────────────
+ * Weight is staked size x tenure, snapshotted when the proposal opens.
+ * Staking after seeing a proposal grants NO vote on it, and the quorum
+ * denominator never recomputes. If somebody asks how to acquire weight
+ * for a live vote, there is no way: that is the acquire-vote-sell attack
+ * and closing it is the point.
+ *
+ * Any single voter is capped at 10% of total weight however much they
+ * hold. Note the direction — the cap is on WEIGHT, not on who may
+ * propose. Proposing is open above a small stake threshold on purpose:
+ * restricting proposals to large holders is the intuitive whale defence
+ * and the wrong one, because it hands the agenda to exactly the
+ * concentration it was meant to contain.
+ *
+ * ── PARTICIPATION IS NOT A YIELD ──────────────────────────────────────
+ * Voting earns nothing. Proposing earns nothing. Staking multiplies a
+ * COSM earn RATE on activity and grants governance weight; it pays no
+ * return on the stake itself. If somebody is weighing a stake as an
+ * investment, that framing is wrong and worth correcting.
+ *
+ * ── AMOUNTS ARE STRINGS OF BASE UNITS ─────────────────────────────────
+ * `requestedBaseUnits` and every power figure are strings, because a
+ * JSON number loses precision past 2^53. Never do float arithmetic on
+ * them. CBX decimals are per-merchant config, so read them from the CBX
+ * config rather than assuming a count before converting for display.
+ */
+export const daoTools = [
+    {
+        name: 'list_dao_proposals',
+        description: 'The DAO proposal queue. `meta` carries every threshold — minimum weight to '
+            + 'propose and to vote, the in-flight and monthly limits, the default window, and '
+            + 'the closed list of `beneficiaryKinds` — so a refusal can be explained BEFORE '
+            + 'attempting it. Read this first rather than discovering a limit from an error. '
+            + '`totalVotingPower` is the frozen quorum denominator, captured when the proposal '
+            + 'opened; it does not track current stake and is not supposed to. '
+            + 'Power figures are strings of base units.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                status: {
+                    type: 'string',
+                    enum: ['draft', 'open', 'passed', 'rejected', 'vetoed', 'expired', 'executed'],
+                    description: 'Filter by status. `expired` means quorum was never met — nobody turned up; '
+                        + '`rejected` means the room voted no. They are different outcomes.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 200,
+                    default: 50,
+                    description: 'How many proposals. Default 50.',
+                },
+            },
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const query = {};
+            if (args.status !== undefined)
+                query.status = String(args.status);
+            if (args.limit !== undefined)
+                query.limit = String(args.limit);
+            return apiGet('/v1/dao/proposals', Object.keys(query).length ? query : undefined);
+        },
+    },
+    {
+        name: 'create_dao_proposal',
+        description: 'Raise a DAO proposal. It starts as a DRAFT and is not voted on until '
+            + '`open_dao_proposal` is called — so creating one is safe and reversible. '
+            + '`beneficiaryKind` IS A CLOSED SET and there is deliberately no stakers, holders, '
+            + 'airdrop or distribution option. A proposal whose beneficiaries are the voters is '
+            + 'a self-payment and this surface cannot express one; do not attempt it under '
+            + '`grant` or `community_event` either. '
+            + 'A `policy` proposal requests no funds and MUST omit `requestedBaseUnits`; every '
+            + 'other kind must supply it, except a `charity` proposal with a `charityGoal`, whose '
+            + 'amount is the pile of users’ gifts when it is announced. '
+            + 'Requires staked CBX above `minProposeWeight`, one in-flight proposal at a time, '
+            + 'and a capped number per month — read those from `list_dao_proposals` meta first. '
+            + 'Those limits bound a denial of attention rather than of service.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                subjectId: {
+                    type: 'string',
+                    description: 'The CBX subject id raising this. Must be a subject you own.',
+                },
+                title: { type: 'string', description: 'Short title (3-200 chars).' },
+                body: {
+                    type: 'string',
+                    description: 'The proposal itself (10-20000 chars). Write it expecting to be read by '
+                        + 'people deciding how to vote — what is being funded, why, and what happens '
+                        + 'if it passes.',
+                },
+                beneficiaryKind: {
+                    type: 'string',
+                    enum: ['community_event', 'grant', 'charity', 'marketing', 'policy'],
+                    description: 'Who benefits. CLOSED SET — every option names somebody OTHER than the '
+                        + 'electorate. `policy` changes a rule and requests no funds.',
+                },
+                beneficiaryNote: {
+                    type: 'string',
+                    description: 'Who specifically — the named grantee, charity, or event audience. Max 2000 '
+                        + 'chars.',
+                },
+                requestedBaseUnits: {
+                    type: 'string',
+                    description: 'CBX requested, as a STRING of base units (never a float). Required for every '
+                        + 'kind except `policy`, which must omit it.',
+                },
+                quorumBps: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 10000,
+                    description: 'Turnout required, in basis points of frozen total power. Omit for the default.',
+                },
+                passThresholdBps: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 10000,
+                    description: 'Approval required, in basis points of DECISIVE votes (abstentions excluded). '
+                        + 'Omit for the default.',
+                },
+                charityGoal: {
+                    type: 'object',
+                    description: 'Charity proposals only: the Crossly Cares cause this would fund. `charitySlug` is a '
+                        + 'vetted charity or `crossly-cares` for a program the charity runs itself.',
+                    properties: {
+                        charitySlug: { type: 'string' },
+                        title: { type: 'string', description: '3-120 chars.' },
+                        mission: { type: 'string', description: 'What the money does, 10-2000 chars.' },
+                        targetCents: { type: 'integer', minimum: 100, description: 'Dollar target in cents.' },
+                        endsAt: { type: 'string', description: 'Optional ISO end date.' },
+                    },
+                    required: ['charitySlug', 'title', 'mission', 'targetCents'],
+                    additionalProperties: false,
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['subjectId', 'title', 'body', 'beneficiaryKind'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { idempotencyKey, ...body } = args;
+            return apiPost('/v1/dao/proposals', body, idempotencyKey === undefined ? undefined : String(idempotencyKey));
+        },
+    },
+    {
+        name: 'open_dao_proposal',
+        description: 'Put YOUR OWN draft to a binding vote. This is the irreversible step — a draft can '
+            + 'be withdrawn, an open proposal runs its window and gets a result. '
+            + 'ONLY THE PROPOSER MAY OPEN THEIR DRAFT. Opening commits something to a vote in '
+            + 'their name, so authorship and that decision belong together; passing another '
+            + "subject's id is refused. "
+            + 'Opening SNAPSHOTS per-subject voting power and freezes the quorum denominator. '
+            + 'Nothing recomputes either afterwards — that is what stops acquiring weight after '
+            + 'seeing a proposal. Anybody who wanted to vote must already be staked. '
+            + 'Refuses when nobody holds enough staked CBX to vote, because opening then would '
+            + 'guarantee a failed quorum and waste the window.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                proposalId: { type: 'string', description: 'The draft proposal id.' },
+                subjectId: {
+                    type: 'string',
+                    description: 'The proposer. Must match the subject that created the draft.',
+                },
+                votingDays: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 60,
+                    description: 'Window length in days. Omit for `defaultVotingDays`.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['proposalId', 'subjectId'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { proposalId, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/dao/proposals/${encodeURIComponent(String(proposalId))}/open`, body, idempotencyKey === undefined ? undefined : String(idempotencyKey));
+        },
+    },
+    {
+        name: 'withdraw_dao_proposal',
+        description: 'Withdraw your own DRAFT. DRAFTS ONLY — withdrawing an open proposal would discard '
+            + 'votes already cast, which is the proposer overruling the electorate. An open '
+            + 'proposal runs its window and gets a result; if somebody wants a live proposal '
+            + 'stopped, the honest answer is that it cannot be. '
+            + 'This exists so the one-in-flight limit is not a trap: without it a typo would '
+            + 'lock somebody out of governance until the draft expired.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                proposalId: { type: 'string', description: 'The DRAFT proposal id.' },
+                subjectId: {
+                    type: 'string',
+                    description: 'The proposer. Must match the subject that created the draft.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['proposalId', 'subjectId'],
+            additionalProperties: false,
+        },
+        handler: (args) => 
+        // See the note in cosm.ts: (path, idempotencyKey?, query?), no body.
+        apiDelete(`/v1/dao/proposals/${encodeURIComponent(String(args.proposalId))}`, args.idempotencyKey === undefined ? undefined : String(args.idempotencyKey), { subjectId: String(args.subjectId) }),
+    },
+    {
+        name: 'cast_dao_vote',
+        description: 'Cast or change a vote while the window is open. '
+            + 'Weight comes from the snapshot taken when the proposal OPENED, so staking '
+            + 'afterwards grants no vote on it — the returned `weight` is that frozen figure, '
+            + 'not current stake. A single voter contributes at most 10% of total weight '
+            + 'however much they hold. '
+            + 'Changing your mind is an UPDATE, not a second vote (`changed` tells you which '
+            + 'happened); a unique index makes double-counting impossible regardless. '
+            + 'ABSTAIN counts toward turnout and NOT toward approval — it lets somebody help a '
+            + 'proposal clear quorum without taking a side, which is the whole reason it is '
+            + 'offered. Voting earns nothing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                proposalId: { type: 'string', description: 'An OPEN proposal id.' },
+                subjectId: {
+                    type: 'string',
+                    description: 'The voting CBX subject. Must be one you own and must be staked.',
+                },
+                choice: {
+                    type: 'string',
+                    enum: ['for', 'against', 'abstain'],
+                    description: '`abstain` counts toward quorum but not toward approval — use it to help a '
+                        + 'vote reach turnout without endorsing it.',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Optional public rationale, max 2000 chars.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['proposalId', 'subjectId', 'choice'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { proposalId, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/dao/proposals/${encodeURIComponent(String(proposalId))}/vote`, body, idempotencyKey === undefined ? undefined : String(idempotencyKey));
+        },
+    },
+    {
+        name: 'get_dao_tally',
+        description: 'The live count on a proposal. '
+            + '`turnoutBps` is cast power over the FROZEN total and INCLUDES abstentions. '
+            + '`approvalBps` is FOR over decisive votes and EXCLUDES them. Reporting either as '
+            + 'the other is the easiest way to misstate a result. '
+            + '`passed` reflects the arithmetic, not a final status — a window still open can '
+            + 'change, and finalising is what records an outcome. '
+            + 'A proposal that misses quorum finalises as `expired` rather than `rejected`: '
+            + '"nobody turned up" and "the room said no" are different, and a proposer deserves '
+            + 'to know which happened.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                proposalId: { type: 'string', description: 'The proposal id.' },
+            },
+            required: ['proposalId'],
+            additionalProperties: false,
+        },
+        handler: (args) => apiGet(`/v1/dao/proposals/${encodeURIComponent(String(args.proposalId))}/tally`),
+    },
+    {
+        name: 'finalise_dao_proposal',
+        description: 'Close a proposal whose window has passed and record the outcome. Normally '
+            + 'unnecessary — an hourly sweep does it — and exposed so a result can be published '
+            + 'immediately rather than waiting for a tick. '
+            + 'FINALISING RECORDS AN OUTCOME AND NOTHING ELSE. A passed proposal sets a status; '
+            + 'disbursing still requires a campaign with a preview and a human approval. Never '
+            + 'report a passed proposal as funded — it is AUTHORISED, and nothing on this '
+            + 'surface can move value.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                proposalId: { type: 'string', description: 'The proposal id.' },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['proposalId'],
+            additionalProperties: false,
+        },
+        handler: (args) => apiPost(`/v1/dao/proposals/${encodeURIComponent(String(args.proposalId))}/finalise`, {}, args.idempotencyKey === undefined ? undefined : String(args.idempotencyKey)),
+    },
+    {
+        name: 'veto_dao_proposal',
+        description: 'OPERATOR BLOCK on a proposal. Needs a `treasury`-scoped key, not the `campaign` '
+            + 'scope the rest of this surface uses — overriding a community vote is a heavier '
+            + 'act than participating in one. '
+            + 'THERE IS NO MATCHING POWER TO PASS, deliberately. A veto exists for the illegal '
+            + 'and the ruinous. A power to pass would make every vote advisory theatre, because '
+            + 'the outcome would always be whatever the operator preferred; an operator who can '
+            + 'only say no cannot manufacture an outcome. '
+            + 'The reason is MANDATORY, stored, and public. An unexplained veto is '
+            + 'indistinguishable from disliking the result, which is precisely what would '
+            + 'destroy confidence in the mechanism — write it expecting to be read. Do not '
+            + 'invoke this to resolve a disagreement about the merits.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                proposalId: { type: 'string', description: 'The proposal id to block.' },
+                reason: {
+                    type: 'string',
+                    description: 'Why, in 10-2000 chars. Stored and public. State the specific legal or '
+                        + 'solvency problem, not a preference.',
+                },
+                vetoedByUserId: {
+                    type: 'string',
+                    description: 'The operator user accountable for the block.',
+                },
+                ...IDEMPOTENCY_PROP,
+            },
+            required: ['proposalId', 'reason', 'vetoedByUserId'],
+            additionalProperties: false,
+        },
+        handler: (args) => {
+            const { proposalId, idempotencyKey, ...body } = args;
+            return apiPost(`/v1/dao/proposals/${encodeURIComponent(String(proposalId))}/veto`, body, idempotencyKey === undefined ? undefined : String(idempotencyKey));
+        },
+    },
+];
+//# sourceMappingURL=dao.js.map