@poa-box/core 0.1.0

package/dist/metadata/org.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Org metadata documents.
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: the subgraph metadata handlers and the
+ * frontend both parse these documents positionally-by-convention, so every
+ * object literal below is constructed with an explicit, load-bearing key
+ * order. Do not reorder, and do not let a spread introduce new keys after
+ * the canonical block.
+ *
+ * Shapes verified against:
+ *   - `pop org deploy`          — src/commands/org/deploy.ts (fresh document)
+ *   - `pop org update-metadata` — src/commands/org/update-metadata.ts (merge)
+ */
+export interface OrgLink {
+    name: string;
+    url: string;
+}
+export interface IndexedOrgLink extends OrgLink {
+    index: number;
+}
+/**
+ * Stamp each link with its array position, exactly like both CLI commands do
+ * (`(links || []).map((l, i) => ({ ...l, index: i }))` — spread first, so any
+ * extra keys on a link survive and `index` lands last / is overwritten).
+ */
+export declare function stampLinkIndices(links: OrgLink[] | undefined | null): IndexedOrgLink[];
+/** Fresh-deploy org metadata document (`pop org deploy`). */
+export interface OrgDeployMetadata {
+    description: string;
+    links: IndexedOrgLink[];
+    template: string;
+    logo: null;
+    backgroundColor: null;
+    hideTreasury: boolean;
+}
+/**
+ * Port of the metadata document `pop org deploy` pins before calling
+ * OrgDeployer.deployFullOrg — src/commands/org/deploy.ts.
+ *
+ * Key order (load-bearing): description, links, template, logo,
+ * backgroundColor, hideTreasury.
+ */
+export declare function buildOrgDeployMetadata(params: {
+    description?: string;
+    links?: OrgLink[];
+}): OrgDeployMetadata;
+/** Fields `pop org update-metadata` lets the caller override. */
+export interface OrgMetadataUpdates {
+    description?: string;
+    /** Replacement link list — index-stamped here; omit to keep current links. */
+    links?: OrgLink[];
+    /** CID of a freshly pinned logo; omit to keep the current logo. */
+    logoCid?: string | null;
+    backgroundColor?: string;
+    hideTreasury?: boolean;
+}
+/**
+ * Canonical merged org metadata (`pop org update-metadata`). The canonical
+ * keys are typed; unknown keys from the current IPFS document ride along
+ * untyped (that is the point of the merge).
+ */
+export interface OrgMetadata {
+    description: string;
+    links: IndexedOrgLink[];
+    template: string;
+    logo: string | null;
+    backgroundColor: string | null;
+    hideTreasury: boolean;
+    useTokenSymbol: boolean;
+    taskPayoutHoursOnly: boolean;
+    taskPayoutHourlyRate: number | null;
+    [key: string]: unknown;
+}
+/**
+ * Port of the merge in `pop org update-metadata` — src/commands/org/update-metadata.ts.
+ *
+ * Build metadata JSON — spread the fetched doc, then override only what was passed.
+ *
+ * Spreading first is what makes this robust: unknown keys survive (e.g.
+ * `zkEmailAllowlist`, which the web settings editor writes and reads back),
+ * and re-assigning an existing key keeps its original position, so a doc
+ * written by the frontend retains the frontend's key order (the subgraph/UI
+ * compatibility rule in CLAUDE.md). The explicit keys below then pin the
+ * canonical order for a doc that lacks them entirely.
+ *
+ * `currentMeta` should be the RAW IPFS document when one exists — the
+ * subgraph's typed projection only carries the fields schema.graphql
+ * declares, so merging over it silently drops everything else.
+ */
+export declare function mergeOrgMetadata(currentMeta: Record<string, any>, updates: OrgMetadataUpdates): OrgMetadata;
+/** Exact serialization both org commands pin (plain JSON.stringify). */
+export declare function serializeOrgMetadata(metadata: OrgDeployMetadata | OrgMetadata): string;

package/dist/metadata/org.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Org metadata documents.
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: the subgraph metadata handlers and the
+ * frontend both parse these documents positionally-by-convention, so every
+ * object literal below is constructed with an explicit, load-bearing key
+ * order. Do not reorder, and do not let a spread introduce new keys after
+ * the canonical block.
+ *
+ * Shapes verified against:
+ *   - `pop org deploy`          — src/commands/org/deploy.ts (fresh document)
+ *   - `pop org update-metadata` — src/commands/org/update-metadata.ts (merge)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stampLinkIndices = stampLinkIndices;
+exports.buildOrgDeployMetadata = buildOrgDeployMetadata;
+exports.mergeOrgMetadata = mergeOrgMetadata;
+exports.serializeOrgMetadata = serializeOrgMetadata;
+/**
+ * Stamp each link with its array position, exactly like both CLI commands do
+ * (`(links || []).map((l, i) => ({ ...l, index: i }))` — spread first, so any
+ * extra keys on a link survive and `index` lands last / is overwritten).
+ */
+function stampLinkIndices(links) {
+    return (links || []).map((l, i) => ({ ...l, index: i }));
+}
+/**
+ * Port of the metadata document `pop org deploy` pins before calling
+ * OrgDeployer.deployFullOrg — src/commands/org/deploy.ts.
+ *
+ * Key order (load-bearing): description, links, template, logo,
+ * backgroundColor, hideTreasury.
+ */
+function buildOrgDeployMetadata(params) {
+    return {
+        description: params.description || '',
+        links: stampLinkIndices(params.links),
+        template: 'default',
+        logo: null,
+        backgroundColor: null,
+        hideTreasury: false,
+    };
+}
+/**
+ * Port of the merge in `pop org update-metadata` — src/commands/org/update-metadata.ts.
+ *
+ * Build metadata JSON — spread the fetched doc, then override only what was passed.
+ *
+ * Spreading first is what makes this robust: unknown keys survive (e.g.
+ * `zkEmailAllowlist`, which the web settings editor writes and reads back),
+ * and re-assigning an existing key keeps its original position, so a doc
+ * written by the frontend retains the frontend's key order (the subgraph/UI
+ * compatibility rule in CLAUDE.md). The explicit keys below then pin the
+ * canonical order for a doc that lacks them entirely.
+ *
+ * `currentMeta` should be the RAW IPFS document when one exists — the
+ * subgraph's typed projection only carries the fields schema.graphql
+ * declares, so merging over it silently drops everything else.
+ */
+function mergeOrgMetadata(currentMeta, updates) {
+    let links = currentMeta.links || [];
+    if (updates.links !== undefined) {
+        links = stampLinkIndices(updates.links);
+    }
+    const metadata = {
+        ...currentMeta,
+        description: updates.description !== undefined ? updates.description : (currentMeta.description || ''),
+        links,
+        template: currentMeta.template || 'default',
+        logo: updates.logoCid || currentMeta.logo || null,
+        backgroundColor: updates.backgroundColor !== undefined ? updates.backgroundColor : (currentMeta.backgroundColor || null),
+        hideTreasury: updates.hideTreasury !== undefined ? updates.hideTreasury : (currentMeta.hideTreasury || false),
+        useTokenSymbol: currentMeta.useTokenSymbol === true,
+        taskPayoutHoursOnly: currentMeta.taskPayoutHoursOnly === true,
+        // BigDecimal arrives from the SUBGRAPH as a STRING ("12.5") while the raw IPFS doc holds
+        // a number. The metadata handler only reads this key when it is JSONValueKind.NUMBER, so
+        // echoing a string back would silently drop the rate. Coerce whichever form we got.
+        taskPayoutHourlyRate: currentMeta.taskPayoutHourlyRate != null
+            && Number.isFinite(Number(currentMeta.taskPayoutHourlyRate))
+            ? Number(currentMeta.taskPayoutHourlyRate)
+            : null,
+    };
+    // Subgraph-entity bookkeeping that is not part of the IPFS document. Only reachable when
+    // the IPFS fetch was skipped because the org has no metadata pointer yet.
+    for (const k of ['id', 'indexedAt', 'organization', '__typename'])
+        delete metadata[k];
+    return metadata;
+}
+/** Exact serialization both org commands pin (plain JSON.stringify). */
+function serializeOrgMetadata(metadata) {
+    return JSON.stringify(metadata);
+}

package/dist/metadata/proposal.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Proposal metadata — the JSON document pinned to IPFS whose bytes32 digest
+ * becomes `descriptionHash` in createProposal.
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: the subgraph and frontend parse this
+ * document, and every CLI site that pins it writes the keys in exactly this
+ * order — {description, optionNames, createdAt} — with no optional keys.
+ * Verified against every pinning site:
+ *   - src/commands/vote/create.ts           (pop vote create)
+ *   - src/commands/vote/propose-quorum.ts   (pop vote propose-quorum)
+ *   - src/commands/vote/propose-config.ts   (pop vote propose-config)
+ *   - src/commands/vote/classes.ts          (pop vote classes propose)
+ *   - src/commands/task/perms.ts            (pop task perms propose-global)
+ *   - src/commands/org/set-metadata-admin.ts, src/commands/project/propose.ts
+ *
+ * The subgraph's ProposalMetadata entity also carries `actionSummaries` and
+ * `promotedFrom` (read by `pop vote results`), but the CLI never writes them
+ * — they come from the frontend's proposal flow. Do NOT add them here without
+ * a verified reference for their position.
+ */
+export interface ProposalMetadata {
+    description: string;
+    optionNames: string[];
+    /** Unix time in MILLISECONDS (the CLI pins Date.now()). */
+    createdAt: number;
+}
+export interface BuildProposalMetadataParams {
+    description: string;
+    optionNames: string[];
+    /** Defaults to Date.now() (milliseconds), matching every CLI pin site. */
+    createdAt?: number;
+}
+/**
+ * Canonical proposal metadata object. Key order is load-bearing — see the
+ * module doc comment. Port of the inline object in `pop vote create`
+ * (src/commands/vote/create.ts) shared by every governance-wrap command.
+ */
+export declare function buildProposalMetadata(params: BuildProposalMetadataParams): ProposalMetadata;
+/**
+ * The exact serialization the CLI pins: JSON.stringify with no spacing.
+ * (The IPFS CID is content-addressed, so byte-identical serialization is what
+ * makes CLI-pinned and core-pinned documents hash identically.)
+ */
+export declare function serializeProposalMetadata(metadata: ProposalMetadata): string;

package/dist/metadata/proposal.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Proposal metadata — the JSON document pinned to IPFS whose bytes32 digest
+ * becomes `descriptionHash` in createProposal.
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: the subgraph and frontend parse this
+ * document, and every CLI site that pins it writes the keys in exactly this
+ * order — {description, optionNames, createdAt} — with no optional keys.
+ * Verified against every pinning site:
+ *   - src/commands/vote/create.ts           (pop vote create)
+ *   - src/commands/vote/propose-quorum.ts   (pop vote propose-quorum)
+ *   - src/commands/vote/propose-config.ts   (pop vote propose-config)
+ *   - src/commands/vote/classes.ts          (pop vote classes propose)
+ *   - src/commands/task/perms.ts            (pop task perms propose-global)
+ *   - src/commands/org/set-metadata-admin.ts, src/commands/project/propose.ts
+ *
+ * The subgraph's ProposalMetadata entity also carries `actionSummaries` and
+ * `promotedFrom` (read by `pop vote results`), but the CLI never writes them
+ * — they come from the frontend's proposal flow. Do NOT add them here without
+ * a verified reference for their position.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProposalMetadata = buildProposalMetadata;
+exports.serializeProposalMetadata = serializeProposalMetadata;
+/**
+ * Canonical proposal metadata object. Key order is load-bearing — see the
+ * module doc comment. Port of the inline object in `pop vote create`
+ * (src/commands/vote/create.ts) shared by every governance-wrap command.
+ */
+function buildProposalMetadata(params) {
+    // Explicit key order: description, optionNames, createdAt.
+    return {
+        description: params.description,
+        optionNames: params.optionNames,
+        createdAt: params.createdAt ?? Date.now(),
+    };
+}
+/**
+ * The exact serialization the CLI pins: JSON.stringify with no spacing.
+ * (The IPFS CID is content-addressed, so byte-identical serialization is what
+ * makes CLI-pinned and core-pinned documents hash identically.)
+ */
+function serializeProposalMetadata(metadata) {
+    return JSON.stringify(metadata);
+}

package/dist/metadata/role.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Role application metadata — the canonical document `pop role apply` pins to
+ * IPFS before calling EligibilityModuleNew.applyForRole(hatId, applicationHash).
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT. The subgraph and frontend read this
+ * document by shape, and the CLI has always pinned exactly
+ * `{ notes, experience, appliedAt }` in that order
+ * (src/commands/role/apply.ts — "key order preserved for frontend/subgraph
+ * parity"). Do not reorder, rename, or interleave keys.
+ */
+/** The pinned document shape. Key order matches the CLI byte-for-byte. */
+export interface RoleApplicationMetadata {
+    /** Application notes; empty string when the applicant provided none. */
+    notes: string;
+    /** Relevant experience; empty string when the applicant provided none. */
+    experience: string;
+    /** Unix MILLISECONDS (Date.now() in the CLI), not seconds. */
+    appliedAt: number;
+}
+export interface RoleApplicationMetadataInput {
+    notes?: string;
+    experience?: string;
+    /** Override the timestamp (unix ms). Default: Date.now(), as the CLI does. */
+    appliedAt?: number;
+}
+/**
+ * Port of `pop role apply`'s metadata construction —
+ * src/commands/role/apply.ts (`applicationData`).
+ *
+ * Key order is load-bearing (see module header): the object literal below is
+ * the canonical order and must not change.
+ */
+export declare function buildRoleApplicationMetadata(input?: RoleApplicationMetadataInput): RoleApplicationMetadata;
+/**
+ * The exact serialization the CLI pins: bare JSON.stringify with no spacing.
+ * `applicationHash` on chain is ipfsCidToBytes32(pinJson(this)).
+ */
+export declare function serializeRoleApplicationMetadata(metadata: RoleApplicationMetadata): string;

package/dist/metadata/role.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Role application metadata — the canonical document `pop role apply` pins to
+ * IPFS before calling EligibilityModuleNew.applyForRole(hatId, applicationHash).
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT. The subgraph and frontend read this
+ * document by shape, and the CLI has always pinned exactly
+ * `{ notes, experience, appliedAt }` in that order
+ * (src/commands/role/apply.ts — "key order preserved for frontend/subgraph
+ * parity"). Do not reorder, rename, or interleave keys.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRoleApplicationMetadata = buildRoleApplicationMetadata;
+exports.serializeRoleApplicationMetadata = serializeRoleApplicationMetadata;
+/**
+ * Port of `pop role apply`'s metadata construction —
+ * src/commands/role/apply.ts (`applicationData`).
+ *
+ * Key order is load-bearing (see module header): the object literal below is
+ * the canonical order and must not change.
+ */
+function buildRoleApplicationMetadata(input = {}) {
+    return {
+        notes: input.notes || '',
+        experience: input.experience || '',
+        appliedAt: input.appliedAt ?? Date.now(),
+    };
+}
+/**
+ * The exact serialization the CLI pins: bare JSON.stringify with no spacing.
+ * `applicationHash` on chain is ipfsCidToBytes32(pinJson(this)).
+ */
+function serializeRoleApplicationMetadata(metadata) {
+    return JSON.stringify(metadata);
+}

package/dist/metadata/task.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Task-domain metadata documents (task, rejection, application, project).
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT. The subgraph's IPFS templates and the
+ * frontend both parse these documents positionally-by-convention: a document
+ * whose keys are serialized in a different order breaks metadata indexing and
+ * the UI. Every builder below constructs its object with an explicit literal
+ * so the JSON.stringify key order is fixed at the source.
+ *
+ * Shapes verified against the CLI commands that pin them:
+ *   task        — src/commands/task/create.ts (buildMetadata in create-batch.ts,
+ *                 the merge sites in submit.ts / update.ts / edit-meta.ts)
+ *   rejection   — src/commands/task/review.ts (reject path)
+ *   application — src/commands/task/apply.ts
+ *   project     — src/commands/project/create.ts + project/propose.ts
+ */
+/**
+ * Canonical task metadata document.
+ *
+ * Exact key order: name, description, location, difficulty, estHours,
+ * submission — and dueDate LAST, present ONLY when set. The subgraph re-points
+ * task.metadata at whatever document was pinned most recently (submitTask,
+ * updateTask, updateTaskMetadata are full overwrites of the pointer), so a
+ * dueDate omitted from a re-pin is deleted for good. Mirrors the frontend,
+ * which appends the key last and only when set.
+ */
+export interface TaskMetadata {
+    name: string;
+    description: string;
+    location: string;
+    difficulty: string;
+    /**
+     * number on create/submit; update/edit-meta pass the subgraph's BigDecimal
+     * STRING through unparsed (`metadata?.estimatedHours || metadata?.estHours
+     * || 0` in update.ts/edit-meta.ts) — preserved for byte parity.
+     */
+    estHours: number | string;
+    submission: string;
+    /**
+     * Soft due date (unix seconds). LAST key, present only when set. May be
+     * NaN-serialized-as-null when a merge carried a garbage raw value — see
+     * buildTaskMetadata.
+     */
+    dueDate?: number | null;
+}
+export interface TaskMetadataFields {
+    name: string;
+    description: string;
+    location: string;
+    difficulty: string;
+    /** See TaskMetadata.estHours for why strings are allowed. */
+    estHours: number | string;
+    submission: string;
+    /**
+     * RAW due-date value (unix seconds, or whatever a merge read back from
+     * IPFS). Truthiness is applied to THIS raw value, coercion happens after —
+     * matching the CLI merge sites exactly. Omit / 0 / '' ⇒ key absent.
+     */
+    dueDate?: number | string;
+}
+/**
+ * Build the canonical task metadata object with the load-bearing key order.
+ *
+ * Deliberately takes FINAL values with no defaulting: the CLI's commands
+ * default differently per site (create uses difficulty 'medium', submit's
+ * merge uses '' — see the Level-2 builders in ../tx/task), so defaults here
+ * would silently change pinned bytes. `dueDate` follows the CLI merge sites'
+ * convention EXACTLY: truthiness on the RAW value, coercion after — so a raw
+ * "0" (truthy string) is pinned as 0, and a truthy non-numeric raw value is
+ * pinned as NaN, which JSON-serializes to null. Testing the coerced number
+ * instead would drop keys the CLI keeps and change the pinned bytes.
+ */
+export declare function buildTaskMetadata(fields: TaskMetadataFields): TaskMetadata;
+/** Serialize exactly as the CLI pins it (JSON.stringify of the ordered object). */
+export declare function serializeTaskMetadata(metadata: TaskMetadata): string;
+/**
+ * Rejection document pinned by `pop task review --action reject`
+ * (src/commands/task/review.ts): a single `rejection` key.
+ */
+export interface TaskRejectionMetadata {
+    rejection: string;
+}
+export declare function buildTaskRejectionMetadata(reason: string): TaskRejectionMetadata;
+export declare function serializeTaskRejectionMetadata(metadata: TaskRejectionMetadata): string;
+/**
+ * Application document pinned by `pop task apply`
+ * (src/commands/task/apply.ts). Key order: notes, experience.
+ */
+export interface TaskApplicationMetadata {
+    notes: string;
+    experience: string;
+}
+export declare function buildTaskApplicationMetadata(fields: {
+    notes?: string;
+    experience?: string;
+}): TaskApplicationMetadata;
+export declare function serializeTaskApplicationMetadata(metadata: TaskApplicationMetadata): string;
+/**
+ * Project metadata document pinned by `pop project create` / `pop project
+ * propose` (src/commands/project/create.ts, project/propose.ts): a single
+ * `description` key. The CLI only pins it when a description was given —
+ * otherwise the on-chain metaHash is HashZero, never a pin of `{description:''}`.
+ */
+export interface ProjectMetadata {
+    description: string;
+}
+export declare function buildProjectMetadata(description: string): ProjectMetadata;
+export declare function serializeProjectMetadata(metadata: ProjectMetadata): string;

package/dist/metadata/task.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Task-domain metadata documents (task, rejection, application, project).
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT. The subgraph's IPFS templates and the
+ * frontend both parse these documents positionally-by-convention: a document
+ * whose keys are serialized in a different order breaks metadata indexing and
+ * the UI. Every builder below constructs its object with an explicit literal
+ * so the JSON.stringify key order is fixed at the source.
+ *
+ * Shapes verified against the CLI commands that pin them:
+ *   task        — src/commands/task/create.ts (buildMetadata in create-batch.ts,
+ *                 the merge sites in submit.ts / update.ts / edit-meta.ts)
+ *   rejection   — src/commands/task/review.ts (reject path)
+ *   application — src/commands/task/apply.ts
+ *   project     — src/commands/project/create.ts + project/propose.ts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTaskMetadata = buildTaskMetadata;
+exports.serializeTaskMetadata = serializeTaskMetadata;
+exports.buildTaskRejectionMetadata = buildTaskRejectionMetadata;
+exports.serializeTaskRejectionMetadata = serializeTaskRejectionMetadata;
+exports.buildTaskApplicationMetadata = buildTaskApplicationMetadata;
+exports.serializeTaskApplicationMetadata = serializeTaskApplicationMetadata;
+exports.buildProjectMetadata = buildProjectMetadata;
+exports.serializeProjectMetadata = serializeProjectMetadata;
+/**
+ * Build the canonical task metadata object with the load-bearing key order.
+ *
+ * Deliberately takes FINAL values with no defaulting: the CLI's commands
+ * default differently per site (create uses difficulty 'medium', submit's
+ * merge uses '' — see the Level-2 builders in ../tx/task), so defaults here
+ * would silently change pinned bytes. `dueDate` follows the CLI merge sites'
+ * convention EXACTLY: truthiness on the RAW value, coercion after — so a raw
+ * "0" (truthy string) is pinned as 0, and a truthy non-numeric raw value is
+ * pinned as NaN, which JSON-serializes to null. Testing the coerced number
+ * instead would drop keys the CLI keeps and change the pinned bytes.
+ */
+function buildTaskMetadata(fields) {
+    const rawDueDate = fields.dueDate;
+    const coerced = Math.floor(Number(rawDueDate));
+    return {
+        name: fields.name,
+        description: fields.description,
+        location: fields.location,
+        difficulty: fields.difficulty,
+        estHours: fields.estHours,
+        submission: fields.submission,
+        // Key order is load-bearing: dueDate is appended LAST and only when the
+        // RAW value is truthy (NaN → null via JSON, same as the CLI).
+        ...(rawDueDate ? { dueDate: Number.isNaN(coerced) ? null : coerced } : {}),
+    };
+}
+/** Serialize exactly as the CLI pins it (JSON.stringify of the ordered object). */
+function serializeTaskMetadata(metadata) {
+    return JSON.stringify(metadata);
+}
+function buildTaskRejectionMetadata(reason) {
+    // Single key — order trivially fixed, kept explicit for symmetry.
+    return { rejection: reason };
+}
+function serializeTaskRejectionMetadata(metadata) {
+    return JSON.stringify(metadata);
+}
+function buildTaskApplicationMetadata(fields) {
+    // Key order is load-bearing: notes, then experience. Empty-string defaults
+    // match the CLI (`argv.notes || ''`).
+    return {
+        notes: fields.notes || '',
+        experience: fields.experience || '',
+    };
+}
+function serializeTaskApplicationMetadata(metadata) {
+    return JSON.stringify(metadata);
+}
+function buildProjectMetadata(description) {
+    return { description };
+}
+function serializeProjectMetadata(metadata) {
+    return JSON.stringify(metadata);
+}

package/dist/metadata/token.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Token-request metadata — the document `pop token request` pins to IPFS.
+ *
+ * Port of the metadata construction in src/commands/token/request.ts:
+ *
+ *   const metadata = { reason: argv.reason, submittedAt: Date.now() };
+ *   pinJson(JSON.stringify(metadata));
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: {reason, submittedAt} matches the
+ * frontend exactly — the subgraph's TokenRequestMetadata mapping and the UI
+ * both consume this document. Do not reorder or insert keys.
+ */
+/** Canonical token-request document. Key order: reason, submittedAt. */
+export interface TokenRequestMetadata {
+    /** Free-text justification for the request (shown to approvers). */
+    reason: string;
+    /** Unix milliseconds at submission time (Date.now() in the CLI/frontend). */
+    submittedAt: number;
+}
+/**
+ * Build the token-request metadata object with the canonical key order.
+ * Port of `pop token request` — src/commands/token/request.ts.
+ *
+ * `submittedAt` defaults to Date.now(), exactly as the CLI does; pass it
+ * explicitly for deterministic documents (tests, replays).
+ */
+export declare function buildTokenRequestMetadata(reason: string, submittedAt?: number): TokenRequestMetadata;
+/**
+ * Serialize with the exact key order the CLI pins
+ * (JSON.stringify of an object constructed as {reason, submittedAt}).
+ */
+export declare function serializeTokenRequestMetadata(metadata: TokenRequestMetadata): string;

package/dist/metadata/token.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Token-request metadata — the document `pop token request` pins to IPFS.
+ *
+ * Port of the metadata construction in src/commands/token/request.ts:
+ *
+ *   const metadata = { reason: argv.reason, submittedAt: Date.now() };
+ *   pinJson(JSON.stringify(metadata));
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: {reason, submittedAt} matches the
+ * frontend exactly — the subgraph's TokenRequestMetadata mapping and the UI
+ * both consume this document. Do not reorder or insert keys.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTokenRequestMetadata = buildTokenRequestMetadata;
+exports.serializeTokenRequestMetadata = serializeTokenRequestMetadata;
+/**
+ * Build the token-request metadata object with the canonical key order.
+ * Port of `pop token request` — src/commands/token/request.ts.
+ *
+ * `submittedAt` defaults to Date.now(), exactly as the CLI does; pass it
+ * explicitly for deterministic documents (tests, replays).
+ */
+function buildTokenRequestMetadata(reason, submittedAt = Date.now()) {
+    // Key order is load-bearing — matches the frontend serialization exactly.
+    return { reason, submittedAt };
+}
+/**
+ * Serialize with the exact key order the CLI pins
+ * (JSON.stringify of an object constructed as {reason, submittedAt}).
+ */
+function serializeTokenRequestMetadata(metadata) {
+    // Rebuilt with explicit key order so callers cannot accidentally pin a
+    // reordered document.
+    return JSON.stringify({ reason: metadata.reason, submittedAt: metadata.submittedAt });
+}

package/dist/metadata/user.d.ts

@@ -0,0 +1,63 @@
+/**
+ * User-profile metadata — the document `pop user update-profile` pins to IPFS
+ * before calling UniversalAccountRegistry.setProfileMetadata.
+ *
+ * Port of the merge logic in src/commands/user/update-profile.ts.
+ *
+ * KEY ORDER IS A PROTOCOL CONTRACT: keys are CONDITIONALLY PRESENT but appear
+ * in the fixed order {bio, avatar, github, twitter, website} — a key is
+ * included when the caller supplies a new value (even an empty string) OR the
+ * existing indexed metadata carries a truthy value for it. The subgraph's
+ * AccountMetadata mapping and the frontend both consume this document; do not
+ * reorder or unconditionally include keys.
+ */
+/** The five profile fields, in canonical document order. */
+export declare const USER_PROFILE_FIELDS: readonly ["bio", "avatar", "github", "twitter", "website"];
+export type UserProfileField = (typeof USER_PROFILE_FIELDS)[number];
+/**
+ * Canonical profile document. Every key is optional (conditionally present),
+ * but present keys always appear in the order bio, avatar, github, twitter,
+ * website.
+ */
+export interface UserProfileMetadata {
+    /** Bio, max 280 chars. */
+    bio?: string;
+    /** Avatar IPFS CID (Qm...). */
+    avatar?: string;
+    /** GitHub username. */
+    github?: string;
+    /** Twitter/X handle. */
+    twitter?: string;
+    /** Website URL. */
+    website?: string;
+}
+/** New values for a profile edit. `undefined` = "leave this field alone". */
+export interface UserProfileUpdates {
+    bio?: string;
+    avatar?: string;
+    github?: string;
+    twitter?: string;
+    website?: string;
+}
+/**
+ * Existing (indexed) metadata being merged over. Values may be null — the
+ * subgraph serves null for unset fields.
+ */
+export type ExistingUserProfileMetadata = Partial<Record<UserProfileField, string | null | undefined>>;
+/**
+ * Read-then-merge profile metadata builder.
+ * Port of `pop user update-profile` — src/commands/user/update-profile.ts.
+ *
+ * Replicates the CLI's inclusion + precedence rules EXACTLY:
+ *   - a key is included when `updates.<k> !== undefined` OR `existing.<k>` is
+ *     truthy (so single-flag edits preserve the other fields, and an explicit
+ *     empty string clears a field while keeping the key);
+ *   - value precedence: updates.<k> ?? existing.<k> ?? '';
+ *   - bio is capped at 280 chars (same error message and exit code).
+ */
+export declare function buildUserProfileMetadata(updates: UserProfileUpdates, existing?: ExistingUserProfileMetadata | null): UserProfileMetadata;
+/**
+ * Serialize with the exact conditional key order the CLI pins. Rebuilt with
+ * explicit ordering so callers cannot accidentally pin a reordered document.
+ */
+export declare function serializeUserProfileMetadata(metadata: UserProfileMetadata): string;