@crowdsource.you/core 1.2.0

package/dist/esm/client.js

@@ -0,0 +1,121 @@
+/**
+ * The client.
+ *
+ * The whole design target is the length of the smallest integration:
+ *
+ *     const crowdsource = new CrowdSource();
+ *     await crowdsource.reports.create({ ... });
+ *
+ * Everything else has a default that is correct for the overwhelming majority of
+ * integrators and a way to override it for the rest. The service key comes from
+ * the environment, the base URL is the one deployment CrowdSource has, and the
+ * envelope, the policy version, the digests, the principal refs and the
+ * idempotency key are all composed rather than configured.
+ *
+ * This client is SERVER-SIDE ONLY. A service credential is the tenant's identity
+ * for its whole moderation stream; shipping one to a browser or a mobile bundle
+ * hands every user of the application the ability to file reports as the
+ * application, read its cases and exhaust its quota. The package depends on
+ * `node:crypto` and does not build for a browser, which is the intended
+ * outcome rather than a limitation to work around.
+ */
+import { Cases, Decisions } from './cases.js';
+import { CommunityNotes } from './communityNotes.js';
+import { parseServiceKey } from './credential.js';
+import { DEFAULT_BASE_URL } from './defaults.js';
+import { CrowdSourceConfigurationError } from './errors.js';
+import { Reports } from './reports.js';
+import { DEFAULT_MAX_ATTEMPTS, DEFAULT_TIMEOUT_MS, Transport, } from './transport.js';
+import { WebhookEndpoints } from './webhookEndpoints.js';
+/** The environment variable a zero-configuration integration reads. */
+export const SERVICE_KEY_ENV_VAR = 'CROWDSOURCE_SERVICE_KEY';
+/** Overrides the service host. Set only when pointing at a local backend. */
+export const BASE_URL_ENV_VAR = 'CROWDSOURCE_BASE_URL';
+export class CrowdSource {
+    constructor(options = {}) {
+        /**
+         * Two ways to be an application, and exactly one of them is configured.
+         *
+         * The Oxy path is checked first so that a deployment which has BOTH — during
+         * the migration off shared secrets — uses the identity it can prove rather
+         * than the secret it still happens to hold. Removing the key is then the
+         * cleanup, not the cutover.
+         */
+        const credential = options.oxyToken
+            ? null
+            : parseServiceKey(options.serviceKey ?? process.env[SERVICE_KEY_ENV_VAR] ?? '');
+        const baseUrl = normalisedBaseUrl(options.baseUrl ?? process.env[BASE_URL_ENV_VAR] ?? DEFAULT_BASE_URL);
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new CrowdSourceConfigurationError('This runtime has no global fetch. Pass one as the `fetch` option.');
+        }
+        const oxyToken = options.oxyToken;
+        const transport = new Transport({
+            baseUrl,
+            bearerToken: credential ? () => credential.bearerToken : () => oxyToken(),
+            timeoutMs,
+            maxAttempts: options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+            fetch: fetchImpl,
+        });
+        this.applicationId = credential ? credential.applicationId : lazyApplicationId(transport);
+        this.reports = new Reports({
+            transport,
+            applicationId: this.applicationId,
+            environment: options.sandbox === true ? 'sandbox' : 'production',
+        });
+        this.cases = new Cases(transport);
+        this.decisions = new Decisions(transport);
+        this.webhookEndpoints = new WebhookEndpoints(transport);
+        this.communityNotes = new CommunityNotes(transport);
+    }
+}
+/**
+ * Asks CrowdSource which application this client is, once.
+ *
+ * Only the Oxy-token path needs this: a service key carries the id inside it.
+ * The promise is created at construction and awaited wherever the id is used,
+ * so the lookup happens at most once per client and never blocks a caller that
+ * does not need it (community notes never do; a report does, because its
+ * envelope names the application and the server refuses one that disagrees).
+ *
+ * A failure is not swallowed into a placeholder id. An envelope carrying the
+ * wrong application is refused by the server anyway, and a client that invented
+ * one would turn a clear "we could not identify you" into a confusing 403 on
+ * every report.
+ */
+function lazyApplicationId(transport) {
+    let pending = null;
+    const resolve = () => (pending ?? (pending = askApplicationId(transport)));
+    // A thenable rather than a promise: nothing is requested until somebody
+    // awaits it, so a client that only reads community notes — which never name
+    // an application — makes no identity call at all. Awaiting it twice still
+    // makes one.
+    return { then: (onFulfilled, onRejected) => resolve().then(onFulfilled, onRejected) };
+}
+function askApplicationId(transport) {
+    return transport
+        .request({ method: 'GET', path: '/v1/applications/me' })
+        .then((body) => {
+        const applicationId = body?.applicationId;
+        if (typeof applicationId !== 'string' || applicationId.length === 0) {
+            throw new CrowdSourceConfigurationError('CrowdSource did not name the application this token belongs to.');
+        }
+        return applicationId;
+    });
+}
+function normalisedBaseUrl(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new CrowdSourceConfigurationError(`'${value}' is not a usable CrowdSource base URL.`);
+    }
+    if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost') {
+        throw new CrowdSourceConfigurationError('A CrowdSource base URL must be https. A service credential sent in clear is a credential you have to rotate.');
+    }
+    // Trailing slashes are stripped so `${baseUrl}/v1/reports` never doubles up.
+    return parsed.origin + parsed.pathname.replace(/\/+$/, '');
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

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

package/dist/esm/communityNotes.js

@@ -0,0 +1,100 @@
+import { CommunityNoteAssignmentBatchSchema, CommunityNoteListSchema, CommunityNoteRatedListSchema, CommunityNoteRatingSchema, CommunityNoteSchema, ShownCommunityNotesSchema, } from '@crowdsource.you/contracts';
+import { sha256Digest } from './digest.js';
+import { CrowdSourceTransportError } from './errors.js';
+/** A stable, header-safe digest of the parts that identify a write. */
+function digestOf(...parts) {
+    return sha256Digest(JSON.stringify(parts)).replace('sha256:', '');
+}
+export class CommunityNotes {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Writes a note. A retry of the same writer's note on the same subject returns it. */
+    async write(submission, options = {}) {
+        return this.parse(CommunityNoteSchema, await this.transport.request({
+            method: 'POST',
+            path: '/v1/community-notes',
+            body: submission,
+            idempotencyKey: options.idempotencyKey ??
+                `community-note.${digestOf(submission.externalSubjectId, submission.authorPrincipalId)}`,
+            signal: options.signal,
+        }), 'a community note');
+    }
+    /** Withdraws a note. Only its writer may; anyone else's note answers 404. */
+    async withdraw(noteId, authorPrincipalId, options = {}) {
+        return this.parse(CommunityNoteSchema, await this.transport.request({
+            method: 'POST',
+            path: `/v1/community-notes/${encodeURIComponent(noteId)}/withdraw`,
+            body: { authorPrincipalId },
+            idempotencyKey: options.idempotencyKey ?? `community-note-withdrawal.${digestOf(noteId)}`,
+            signal: options.signal,
+        }), 'a community note');
+    }
+    /**
+     * Draws notes for one rater to rate — the ONLY way to be allowed to rate one.
+     *
+     * `idempotencyKey` is required: a retry with the same key returns the same
+     * batch, and a new key is a new draw.
+     */
+    async drawToRate(request, options) {
+        const batch = this.parse(CommunityNoteAssignmentBatchSchema, await this.transport.request({
+            method: 'POST',
+            path: '/v1/community-notes/assignments',
+            body: request,
+            idempotencyKey: options.idempotencyKey,
+            signal: options.signal,
+        }), 'a batch of community note assignments');
+        return batch.assignments;
+    }
+    /** Rates a note assigned to the rater. Final: a second rating is refused. */
+    async rate(noteId, submission, options = {}) {
+        return this.parse(CommunityNoteRatingSchema, await this.transport.request({
+            method: 'POST',
+            path: `/v1/community-notes/${encodeURIComponent(noteId)}/ratings`,
+            body: submission,
+            idempotencyKey: options.idempotencyKey ?? `community-note-rating.${digestOf(noteId, submission.raterPrincipalId)}`,
+            signal: options.signal,
+        }), 'a community note rating');
+    }
+    /** The shown note, if any, for each of up to 50 subjects. */
+    async shown(externalSubjectIds, options = {}) {
+        const subjects = [...new Set(externalSubjectIds)];
+        if (subjects.length === 0)
+            return [];
+        const response = this.parse(ShownCommunityNotesSchema, await this.transport.request({
+            method: 'GET',
+            path: `/v1/community-notes/shown?subjects=${subjects.map(encodeURIComponent).join(',')}`,
+            signal: options.signal,
+        }), 'a shown community notes lookup');
+        return response.notes;
+    }
+    /** A writer's own notes, newest first. */
+    async writtenBy(authorPrincipalId, options = {}) {
+        const response = this.parse(CommunityNoteListSchema, await this.transport.request({
+            method: 'GET',
+            path: `/v1/community-notes/principals/${encodeURIComponent(authorPrincipalId)}/notes`,
+            signal: options.signal,
+        }), 'a list of community notes');
+        return response.notes;
+    }
+    /** A rater's own ratings, each with the note it rated, newest first. */
+    async ratedBy(raterPrincipalId, options = {}) {
+        const response = this.parse(CommunityNoteRatedListSchema, await this.transport.request({
+            method: 'GET',
+            path: `/v1/community-notes/principals/${encodeURIComponent(raterPrincipalId)}/ratings`,
+            signal: options.signal,
+        }), 'a list of community note ratings');
+        return response.ratings;
+    }
+    parse(schema, response, what) {
+        const parsed = schema.safeParse(response);
+        if (!parsed.success) {
+            throw new CrowdSourceTransportError(`CrowdSource answered with ${what} this client does not recognise.`, {
+                retryable: false,
+                cause: parsed.error,
+            });
+        }
+        return parsed.data;
+    }
+}
+//# sourceMappingURL=communityNotes.js.map

package/dist/esm/communityNotes.js.map

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

package/dist/esm/credential.js

@@ -0,0 +1,67 @@
+/**
+ * The service key, and the only place `applicationId` may come from.
+ *
+ * Appendix F: "`applicationId` comes from the credential, never from the request
+ * body." The backend already honours that — it derives the tenant from the
+ * presented token and 403s an envelope naming a different application. But the
+ * Case Envelope contract still REQUIRES `applicationId` on the wire, so a client
+ * has to put one there, and the question this module answers is where it gets it
+ * from without ever asking the integrator.
+ *
+ * The answer is that it comes out of the credential, literally. CrowdSource
+ * issues three values together (`provisioning.service.ts`
+ * `IssuedCredential`): the application the credential belongs to, the credential
+ * id, and the secret. Joined into ONE opaque string, they are a single
+ * environment variable an integrator pastes and never reads — and the
+ * `applicationId` in an envelope is then a value the client READ OFF THE
+ * CREDENTIAL, not a parameter anyone can pass. There is no `applicationId`
+ * option on the client, none on any method, and none an envelope input can
+ * carry; supplying one is not "discouraged", it is unexpressible.
+ *
+ * `:` is the separator because the contract's identifier grammar excludes it and
+ * credential secrets are base64url, so the split is unambiguous for every value
+ * CrowdSource can issue. A `.` separator would not be: `IdentifierSchema` allows
+ * dots inside an id.
+ *
+ * NOTE FOR THE CONSOLE: `issueApplicationCredential` returns the three values
+ * separately and the bearer token as `<credentialId>.<secret>`. Whatever surface
+ * shows an integrator their key must show `formatServiceKey(issued)` — the
+ * composite below — or the integrator has two values to configure instead of
+ * one, and the client has no way to know its own application.
+ */
+import { IdentifierSchema } from '@crowdsource.you/contracts';
+import { CrowdSourceConfigurationError } from './errors.js';
+const SERVICE_KEY_SEPARATOR = ':';
+/** The three values `issueApplicationCredential` returns, as one opaque key. */
+export function formatServiceKey(issued) {
+    return [issued.applicationId, issued.credentialId, issued.secret].join(SERVICE_KEY_SEPARATOR);
+}
+/**
+ * Parses a service key.
+ *
+ * Every rejection names which part is wrong and none of them echoes the secret:
+ * a configuration error is read from a log, and a log line is the second most
+ * common way a credential leaks after a screenshot.
+ */
+export function parseServiceKey(serviceKey) {
+    const trimmed = serviceKey.trim();
+    if (!trimmed) {
+        throw new CrowdSourceConfigurationError('The CrowdSource service key is empty.');
+    }
+    const parts = trimmed.split(SERVICE_KEY_SEPARATOR);
+    if (parts.length !== 3) {
+        throw new CrowdSourceConfigurationError(`A CrowdSource service key is three colon-separated parts (applicationId:credentialId:secret); this one has ${parts.length}.`);
+    }
+    const [applicationId, credentialId, secret] = parts;
+    if (!IdentifierSchema.safeParse(applicationId).success) {
+        throw new CrowdSourceConfigurationError('The first part of a CrowdSource service key must be the applicationId it was issued for.');
+    }
+    if (!IdentifierSchema.safeParse(credentialId).success) {
+        throw new CrowdSourceConfigurationError('The second part of a CrowdSource service key must be the credentialId it was issued for.');
+    }
+    if (!secret) {
+        throw new CrowdSourceConfigurationError('The third part of a CrowdSource service key must be the credential secret.');
+    }
+    return { applicationId, credentialId, bearerToken: `${credentialId}.${secret}` };
+}
+//# sourceMappingURL=credential.js.map

package/dist/esm/credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.js","sourceRoot":"","sources":["../../src/credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAE5D,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAelC,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,MAIhC;IACC,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAChG,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,6BAA6B,CAAC,uCAAuC,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,6BAA6B,CACrC,8GAA8G,KAAK,CAAC,MAAM,GAAG,CAC9H,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,aAAa,EAAE,YAAY,EAAE,MAAM,CAAC,GAAG,KAAK,CAAC;IAEpD,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE,CAAC;QACvD,MAAM,IAAI,6BAA6B,CACrC,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC;QACtD,MAAM,IAAI,6BAA6B,CACrC,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,6BAA6B,CACrC,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,YAAY,IAAI,MAAM,EAAE,EAAE,CAAC;AACnF,CAAC"}

package/dist/esm/defaults.js

@@ -0,0 +1,77 @@
+/**
+ * What an integrator does not have to declare, and why each default is safe to
+ * apply without being asked.
+ *
+ * The product requirement is near-zero configuration: an application should be
+ * able to report a piece of content with a credential and the object itself. The
+ * plan's requirement pulling the other way is §6.4 — every decision records the
+ * policy version it was decided under, and a policy update must never silently
+ * change what a past decision meant.
+ *
+ * Both hold only if the default is a PINNED VERSION rather than "whatever is
+ * current". `DEFAULT_POLICY` below names a specific immutable published version.
+ * When CrowdSource publishes a newer baseline, this constant changes in a
+ * release of this package and integrators adopt it by upgrading — which is
+ * visible in a lockfile, reviewable in a diff, and dated. The alternative
+ * (resolving "latest" server-side) would move the policy version under an
+ * application that never changed a line, and would silently split
+ * `caseDedupKey` — §7.3 makes the policy version part of that key, so the day it
+ * moved, two reports about one post would open two cases.
+ */
+/** Where the service lives. One deployment; there is no sandbox host. */
+export const DEFAULT_BASE_URL = 'https://api.crowdsource.oxy.so';
+/**
+ * The policy set a report is evaluated under when the application declares
+ * none: the baseline CrowdSource ships over its own universal taxonomy (§6.3).
+ *
+ * Must stay equal to `BASELINE_POLICY_SET_ID` / `BASELINE_POLICY_VERSION` in the
+ * backend's `modules/policy/policyBaseline.ts`, which is the registry that
+ * resolves it. A drift is not a type error and not a test failure anywhere else:
+ * it is a 422 on every zero-config report, in production, at the moment of
+ * upgrade. `__tests__/defaults.test.ts` reads that file and asserts the pair.
+ */
+export const DEFAULT_POLICY = Object.freeze({
+    policySetId: 'crowdsource.baseline',
+    version: '2026.07',
+});
+/**
+ * §13.6's default retention: 30 days after a final decision, configurable by
+ * policy.
+ */
+export const DEFAULT_RETENTION_DAYS = 30;
+/**
+ * Allegation codes that must never reach a community jury (§7.5).
+ *
+ * §7.5 routes child sexual abuse and potentially illegal material to a
+ * specialist team under legal protocol, and non-consensual intimate material to
+ * specialist review. An integrator who never read §7.5 still gets that: an
+ * envelope alleging one of these is composed with `allowCommunityReview: false`,
+ * and an application that explicitly asks for `true` alongside one of them is
+ * REFUSED rather than quietly corrected — the belief that this material can be
+ * community-reviewed is the defect, and silently fixing the field would leave
+ * the belief in place.
+ *
+ * This is a floor, never a ceiling. Triage may route a case away from the
+ * community for reasons this list cannot see; nothing here can route one
+ * towards it.
+ */
+export const COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS = Object.freeze([
+    'child_safety.sexualization',
+    'child_safety.grooming',
+    'child_safety.exploitation',
+    'sexual_content.non_consensual',
+    'sexual_content.exploitation',
+]);
+const FORBIDDEN_SET = new Set(COMMUNITY_REVIEW_FORBIDDEN_ALLEGATIONS);
+/** The allegations in `codes` that §7.5 keeps away from a community jury. */
+export function allegationsForbiddingCommunityReview(codes) {
+    return codes.filter((code) => FORBIDDEN_SET.has(code));
+}
+/** The privacy terms of a report that declares none. */
+export function defaultPrivacy(allegationCodes) {
+    return {
+        retentionDays: DEFAULT_RETENTION_DAYS,
+        allowCommunityReview: allegationsForbiddingCommunityReview(allegationCodes).length === 0,
+    };
+}
+//# sourceMappingURL=defaults.js.map

package/dist/esm/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,gCAAgC,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkB,MAAM,CAAC,MAAM,CAAC;IACzD,WAAW,EAAE,sBAAsB;IACnC,OAAO,EAAE,SAAS;CACnB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,sCAAsC,GAA4B,MAAM,CAAC,MAAM,CAAC;IAC3F,4BAA4B;IAC5B,uBAAuB;IACvB,2BAA2B;IAC3B,+BAA+B;IAC/B,6BAA6B;CAC9B,CAAC,CAAC;AAEH,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,sCAAsC,CAAC,CAAC;AAE3F,6EAA6E;AAC7E,MAAM,UAAU,oCAAoC,CAClD,KAA8B;IAE9B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,cAAc,CAAC,eAAwC;IACrE,OAAO;QACL,aAAa,EAAE,sBAAsB;QACrC,oBAAoB,EAAE,oCAAoC,CAAC,eAAe,CAAC,CAAC,MAAM,KAAK,CAAC;KACzF,CAAC;AACJ,CAAC"}

package/dist/esm/digest.js

@@ -0,0 +1,74 @@
+/**
+ * Resource digests (§5.2 `sha256`, §5.6 "SHA 256 of each resource").
+ *
+ * Every inline resource in an envelope must carry a digest of "the exact
+ * representation reviewed", and asking an integrator to compute one is asking
+ * them to get canonical serialisation right — which they will do differently
+ * from the next integrator, and differently again from themselves next quarter.
+ * So the client computes it, from one rule applied to every resource type:
+ *
+ *     sha256:<hex of SHA-256 over canonicalJson({ type, data }) in UTF-8>
+ *
+ * `type` is inside the digest so a `text` resource and a `metadata` resource
+ * carrying identical fields do not produce the same digest. `custom` hashes its
+ * registered `schemaId` and `payload` for the same reason.
+ *
+ * Determinism is not a nicety here, it is the deduplication invariant. §7.3
+ * requires two people reporting the same version of the same post to land on ONE
+ * case, and the server's `caseDedupKey` is computed over a projection of the
+ * envelope that INCLUDES every resource verbatim, digest and all. A digest that
+ * varied with key order — or with which reporter sent it — would give the same
+ * post two cases, and "one penalty per incident" would be broken by a JSON
+ * serialiser.
+ *
+ * Asset-backed resources are the exception the contract already makes: their
+ * bytes live outside the envelope and `asset.sha256` is the digest of those
+ * bytes, so nothing here computes one for them.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * JSON with object keys in a fixed order and `undefined` members dropped.
+ *
+ * Array order is PRESERVED. In a conversation's `messageResourceIds` the order
+ * is the meaning, and the backend's own canonicaliser makes the same choice for
+ * the same reason.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new TypeError('A resource cannot carry a non-finite number: it has no JSON form.');
+        }
+        return JSON.stringify(value);
+    }
+    if (isCanonicalArray(value)) {
+        return `[${value.map((entry) => canonicalJson(entry)).join(',')}]`;
+    }
+    const members = Object.keys(value)
+        .sort()
+        .flatMap((key) => {
+        const member = value[key];
+        return member === undefined ? [] : [`${JSON.stringify(key)}:${canonicalJson(member)}`];
+    });
+    return `{${members.join(',')}}`;
+}
+/**
+ * A written-out predicate rather than a bare `Array.isArray`, because
+ * `Array.isArray` narrows `readonly T[]` in its TRUE branch only — the false
+ * branch keeps the array in the union and the object branch below stops
+ * type-checking.
+ */
+function isCanonicalArray(value) {
+    return Array.isArray(value);
+}
+/** `sha256:<64 lowercase hex>` — the only digest form the contract accepts. */
+export function sha256Digest(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+/** The digest of an inline resource's reviewable representation. */
+export function resourceDigest(reviewable) {
+    return sha256Digest(Buffer.from(canonicalJson(reviewable), 'utf8'));
+}
+//# sourceMappingURL=digest.js.map

package/dist/esm/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../src/digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAWzC;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAqB;IACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9E,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACrE,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;SAC/B,IAAI,EAAE;SACN,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE;QACf,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;IAEL,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAqB;IAC7C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,KAA0B;IACrD,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AACtE,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,UAA0B;IACvD,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC"}