@crowdsource.you/core 1.2.0

package/dist/cases.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * `GET /v1/cases/{id}` and `GET /v1/decisions/{id}` (§10.2).
+ *
+ * Both are look-ups by an id CrowdSource gave the application. There is no case
+ * search and there will not be one: "nobody chooses the case they review" is an
+ * invariant, and a list endpoint on the application API would be the first step
+ * towards a queue somebody browses.
+ *
+ * `decisions.get` is written against the route §10.2 defines. **The backend does
+ * not serve it yet** — nothing publishes decisions, because sortition, review
+ * and consensus are not built — so it answers 404 today. It is here because a
+ * client of a documented endpoint is not a stub, and because the webhook path
+ * (`case.decided`) is how an application learns about a decision anyway; this is
+ * the read-back for one it already has an id for.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Decisions = exports.Cases = void 0;
+const contracts_1 = require("@crowdsource.you/contracts");
+const zod_1 = require("zod");
+const errors_js_1 = require("./errors.js");
+const CaseViewSchema = zod_1.z.looseObject({
+    caseId: zod_1.z.string(),
+    status: zod_1.z.string(),
+    subject: zod_1.z.looseObject({ externalId: zod_1.z.string(), type: zod_1.z.string() }),
+    policy: zod_1.z.looseObject({ policySetId: zod_1.z.string(), version: zod_1.z.string() }),
+    taxonomyVersion: zod_1.z.string(),
+    allegationCodes: zod_1.z.array(zod_1.z.string()),
+    reportCount: zod_1.z.number(),
+    sensitivityClass: zod_1.z.string(),
+    currentRevision: zod_1.z.number(),
+    createdAt: zod_1.z.string(),
+    updatedAt: zod_1.z.string(),
+});
+class Cases {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async get(caseId, options = {}) {
+        const response = await this.transport.request({
+            method: 'GET',
+            path: `/v1/cases/${encodeURIComponent(caseId)}`,
+            signal: options.signal,
+        });
+        const parsed = CaseViewSchema.safeParse(response);
+        if (!parsed.success) {
+            throw new errors_js_1.CrowdSourceTransportError('CrowdSource answered with a case this client does not recognise.', { retryable: false, cause: parsed.error });
+        }
+        return parsed.data;
+    }
+}
+exports.Cases = Cases;
+class Decisions {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Reads one immutable revision of a decision.
+     *
+     * A published revision is never edited (Appendix F); a later revision
+     * supersedes it and carries `supersedesDecisionId`. So a decision read twice
+     * is byte-identical, and an application that cached one never needs to
+     * invalidate it — it needs to notice a `decision.corrected` webhook.
+     */
+    async get(decisionId, options = {}) {
+        const response = await this.transport.request({
+            method: 'GET',
+            path: `/v1/decisions/${encodeURIComponent(decisionId)}`,
+            signal: options.signal,
+        });
+        const parsed = contracts_1.DecisionSchema.safeParse(response);
+        if (!parsed.success) {
+            throw new errors_js_1.CrowdSourceTransportError('CrowdSource answered with a decision this client does not recognise.', { retryable: false, cause: parsed.error });
+        }
+        return parsed.data;
+    }
+}
+exports.Decisions = Decisions;
+//# sourceMappingURL=cases.js.map

package/dist/cases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cases.js","sourceRoot":"","sources":["../src/cases.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,0DAA8F;AAC9F,6BAAwB;AAExB,2CAAwD;AAyBxD,MAAM,cAAc,GAAG,OAAC,CAAC,WAAW,CAAC;IACnC,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,OAAO,EAAE,OAAC,CAAC,WAAW,CAAC,EAAE,UAAU,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IACpE,MAAM,EAAE,OAAC,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IACvE,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE;IAC3B,eAAe,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC;IACpC,WAAW,EAAE,OAAC,CAAC,MAAM,EAAE;IACvB,gBAAgB,EAAE,OAAC,CAAC,MAAM,EAAE;IAC5B,eAAe,EAAE,OAAC,CAAC,MAAM,EAAE;IAC3B,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;IACrB,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC;AAMH,MAAa,KAAK;IAGhB,YAAY,SAAoB;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,MAAc,EAAE,UAAuB,EAAE;QACjD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACrD,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,aAAa,kBAAkB,CAAC,MAAM,CAAC,EAAE;YAC/C,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,qCAAyB,CACjC,kEAAkE,EAClE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAC1C,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;CACF;AAvBD,sBAuBC;AAED,MAAa,SAAS;IAGpB,YAAY,SAAoB;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,GAAG,CAAC,UAAkB,EAAE,UAAuB,EAAE;QACrD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACrD,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,iBAAiB,kBAAkB,CAAC,UAAU,CAAC,EAAE;YACvD,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,0BAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,qCAAyB,CACjC,sEAAsE,EACtE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAC1C,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;CACF;AA/BD,8BA+BC"}

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 { Reports } from './reports.js';
+import { type FetchLike } from './transport.js';
+import { WebhookEndpoints } from './webhookEndpoints.js';
+/** The environment variable a zero-configuration integration reads. */
+export declare const SERVICE_KEY_ENV_VAR = "CROWDSOURCE_SERVICE_KEY";
+/** Overrides the service host. Set only when pointing at a local backend. */
+export declare const BASE_URL_ENV_VAR = "CROWDSOURCE_BASE_URL";
+export interface CrowdSourceOptions {
+    /**
+     * The service key CrowdSource issued, as one opaque string. Defaults to
+     * `process.env.CROWDSOURCE_SERVICE_KEY`.
+     *
+     * There is no `applicationId` option here or anywhere else. The application a
+     * report belongs to is read off this credential — see `credential.ts`.
+     */
+    readonly serviceKey?: string;
+    /**
+     * A first-party Oxy service authenticating with NO CrowdSource credential.
+     *
+     * Return a current Oxy service token; it is asked for once per request
+     * attempt, so returning a cached token and refreshing it when it expires is
+     * the expected shape (`oxyServices.getServiceToken()` does exactly that).
+     *
+     * With this set, `serviceKey` is neither needed nor read. CrowdSource resolves
+     * the tenant from the Oxy application the token names, so nothing here has to
+     * be issued, stored or rotated by a person. Third parties keep the service
+     * key: they run where Oxy cannot vouch for them.
+     */
+    readonly oxyToken?: () => string | Promise<string>;
+    readonly baseUrl?: string;
+    /** Per-attempt deadline. Default 10s. */
+    readonly timeoutMs?: number;
+    /** Attempts per call including the first, for retryable failures. Default 3. */
+    readonly maxAttempts?: number;
+    /**
+     * Marks reports as coming from the application's own pre-production (§5.1
+     * `source.environment`). CrowdSource has one deployment; this is a property of
+     * the report, not a different host to talk to.
+     *
+     * Every report from a sandbox client must carry `submittedAt`, because the
+     * environment travels inside `source` and `source` cannot be composed without
+     * one — see `ReportInput.submittedAt` for why inventing that timestamp would
+     * turn every retry into a 409.
+     */
+    readonly sandbox?: boolean;
+    /** Injected for tests and for the in-process sandbox. Defaults to global `fetch`. */
+    readonly fetch?: FetchLike;
+}
+export declare class CrowdSource {
+    /**
+     * The application this client acts as.
+     *
+     * Read off the credential when there is one. With an Oxy token there is
+     * nothing to read it off — the mapping lives in CrowdSource — so it resolves
+     * on first use from `GET /v1/applications/me` and is remembered.
+     */
+    readonly applicationId: string | Promise<string>;
+    readonly reports: Reports;
+    readonly cases: Cases;
+    readonly decisions: Decisions;
+    /** Where decisions get delivered, and the secret that signs them (§10.2). */
+    readonly webhookEndpoints: WebhookEndpoints;
+    /** Community notes: write, withdraw, draw to rate, rate, and the reads. */
+    readonly communityNotes: CommunityNotes;
+    constructor(options?: CrowdSourceOptions);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,4BAA4B,CAAC;AAE7D,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED,qBAAa,WAAW;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;gBAE5B,OAAO,GAAE,kBAAuB;CA4C7C"}

package/dist/client.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrowdSource = exports.BASE_URL_ENV_VAR = exports.SERVICE_KEY_ENV_VAR = void 0;
+const cases_js_1 = require("./cases.js");
+const communityNotes_js_1 = require("./communityNotes.js");
+const credential_js_1 = require("./credential.js");
+const defaults_js_1 = require("./defaults.js");
+const errors_js_1 = require("./errors.js");
+const reports_js_1 = require("./reports.js");
+const transport_js_1 = require("./transport.js");
+const webhookEndpoints_js_1 = require("./webhookEndpoints.js");
+/** The environment variable a zero-configuration integration reads. */
+exports.SERVICE_KEY_ENV_VAR = 'CROWDSOURCE_SERVICE_KEY';
+/** Overrides the service host. Set only when pointing at a local backend. */
+exports.BASE_URL_ENV_VAR = 'CROWDSOURCE_BASE_URL';
+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
+            : (0, credential_js_1.parseServiceKey)(options.serviceKey ?? process.env[exports.SERVICE_KEY_ENV_VAR] ?? '');
+        const baseUrl = normalisedBaseUrl(options.baseUrl ?? process.env[exports.BASE_URL_ENV_VAR] ?? defaults_js_1.DEFAULT_BASE_URL);
+        const timeoutMs = options.timeoutMs ?? transport_js_1.DEFAULT_TIMEOUT_MS;
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new errors_js_1.CrowdSourceConfigurationError('This runtime has no global fetch. Pass one as the `fetch` option.');
+        }
+        const oxyToken = options.oxyToken;
+        const transport = new transport_js_1.Transport({
+            baseUrl,
+            bearerToken: credential ? () => credential.bearerToken : () => oxyToken(),
+            timeoutMs,
+            maxAttempts: options.maxAttempts ?? transport_js_1.DEFAULT_MAX_ATTEMPTS,
+            fetch: fetchImpl,
+        });
+        this.applicationId = credential ? credential.applicationId : lazyApplicationId(transport);
+        this.reports = new reports_js_1.Reports({
+            transport,
+            applicationId: this.applicationId,
+            environment: options.sandbox === true ? 'sandbox' : 'production',
+        });
+        this.cases = new cases_js_1.Cases(transport);
+        this.decisions = new cases_js_1.Decisions(transport);
+        this.webhookEndpoints = new webhookEndpoints_js_1.WebhookEndpoints(transport);
+        this.communityNotes = new communityNotes_js_1.CommunityNotes(transport);
+    }
+}
+exports.CrowdSource = CrowdSource;
+/**
+ * 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 errors_js_1.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 errors_js_1.CrowdSourceConfigurationError(`'${value}' is not a usable CrowdSource base URL.`);
+    }
+    if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost') {
+        throw new errors_js_1.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/client.js.map

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

package/dist/communityNotes.d.ts

@@ -0,0 +1,49 @@
+import { type CommunityNote, type CommunityNoteAssignment, type CommunityNoteAssignmentRequest, type CommunityNoteRatedList, type CommunityNoteRating, type CommunityNoteRatingSubmission, type CommunityNoteSubmission } from '@crowdsource.you/contracts';
+import type { Transport } from './transport.js';
+/**
+ * Community notes (`docs/architecture/community-notes.md`): reader-written context
+ * under the application's subjects, shown once raters of different viewpoints
+ * agree it is helpful.
+ *
+ * The application acts for its users, naming each by its own opaque principal id.
+ * Every write is retry-safe with no key from the caller where one can be derived
+ * from what the write IS — one note per writer per subject, one rating per rater
+ * per note — and the derived keys hash the principal ids, so an application's
+ * user ids never travel in a header a proxy might log. Drawing notes to rate has
+ * no such identity (two draws for one rater are two different requests), so that
+ * one method takes the key from the caller.
+ */
+export interface CommunityNoteRequestOptions {
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+export interface CommunityNoteReadOptions {
+    readonly signal?: AbortSignal;
+}
+export declare class CommunityNotes {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Writes a note. A retry of the same writer's note on the same subject returns it. */
+    write(submission: CommunityNoteSubmission, options?: CommunityNoteRequestOptions): Promise<CommunityNote>;
+    /** Withdraws a note. Only its writer may; anyone else's note answers 404. */
+    withdraw(noteId: string, authorPrincipalId: string, options?: CommunityNoteRequestOptions): Promise<CommunityNote>;
+    /**
+     * 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.
+     */
+    drawToRate(request: CommunityNoteAssignmentRequest, options: CommunityNoteRequestOptions & {
+        readonly idempotencyKey: string;
+    }): Promise<CommunityNoteAssignment[]>;
+    /** Rates a note assigned to the rater. Final: a second rating is refused. */
+    rate(noteId: string, submission: CommunityNoteRatingSubmission, options?: CommunityNoteRequestOptions): Promise<CommunityNoteRating>;
+    /** The shown note, if any, for each of up to 50 subjects. */
+    shown(externalSubjectIds: readonly string[], options?: CommunityNoteReadOptions): Promise<CommunityNote[]>;
+    /** A writer's own notes, newest first. */
+    writtenBy(authorPrincipalId: string, options?: CommunityNoteReadOptions): Promise<CommunityNote[]>;
+    /** A rater's own ratings, each with the note it rated, newest first. */
+    ratedBy(raterPrincipalId: string, options?: CommunityNoteReadOptions): Promise<CommunityNoteRatedList['ratings']>;
+    private parse;
+}
+//# sourceMappingURL=communityNotes.d.ts.map

package/dist/communityNotes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"communityNotes.d.ts","sourceRoot":"","sources":["../src/communityNotes.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,aAAa,EAClB,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,6BAA6B,EAClC,KAAK,uBAAuB,EAC7B,MAAM,4BAA4B,CAAC;AAKpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAOD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,SAAS,EAAE,SAAS;IAIhC,uFAAuF;IACjF,KAAK,CAAC,UAAU,EAAE,uBAAuB,EAAE,OAAO,GAAE,2BAAgC,GAAG,OAAO,CAAC,aAAa,CAAC;IAgBnH,6EAA6E;IACvE,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,aAAa,CAAC;IAczB;;;;;OAKG;IACG,UAAU,CACd,OAAO,EAAE,8BAA8B,EACvC,OAAO,EAAE,2BAA2B,GAAG;QAAE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAAE,GACzE,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAerC,6EAA6E;IACvE,IAAI,CACR,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,6BAA6B,EACzC,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,mBAAmB,CAAC;IAe/B,6DAA6D;IACvD,KAAK,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAepH,0CAA0C;IACpC,SAAS,CAAC,iBAAiB,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAa5G,wEAAwE;IAClE,OAAO,CACX,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,sBAAsB,CAAC,SAAS,CAAC,CAAC;IAa7C,OAAO,CAAC,KAAK;CAUd"}

package/dist/communityNotes.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommunityNotes = void 0;
+const contracts_1 = require("@crowdsource.you/contracts");
+const digest_js_1 = require("./digest.js");
+const errors_js_1 = require("./errors.js");
+/** A stable, header-safe digest of the parts that identify a write. */
+function digestOf(...parts) {
+    return (0, digest_js_1.sha256Digest)(JSON.stringify(parts)).replace('sha256:', '');
+}
+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(contracts_1.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(contracts_1.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(contracts_1.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(contracts_1.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(contracts_1.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(contracts_1.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(contracts_1.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 errors_js_1.CrowdSourceTransportError(`CrowdSource answered with ${what} this client does not recognise.`, {
+                retryable: false,
+                cause: parsed.error,
+            });
+        }
+        return parsed.data;
+    }
+}
+exports.CommunityNotes = CommunityNotes;
+//# sourceMappingURL=communityNotes.js.map

package/dist/communityNotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"communityNotes.js","sourceRoot":"","sources":["../src/communityNotes.ts"],"names":[],"mappings":";;;AAAA,0DAcoC;AAGpC,2CAA2C;AAC3C,2CAAwD;AA0BxD,uEAAuE;AACvE,SAAS,QAAQ,CAAC,GAAG,KAAwB;IAC3C,OAAO,IAAA,wBAAY,EAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACpE,CAAC;AAED,MAAa,cAAc;IAGzB,YAAY,SAAoB;QAC9B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,KAAK,CAAC,UAAmC,EAAE,UAAuC,EAAE;QACxF,OAAO,IAAI,CAAC,KAAK,CACf,+BAAmB,EACnB,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACpC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,qBAAqB;YAC3B,IAAI,EAAE,UAAU;YAChB,cAAc,EACZ,OAAO,CAAC,cAAc;gBACtB,kBAAkB,QAAQ,CAAC,UAAU,CAAC,iBAAiB,EAAE,UAAU,CAAC,iBAAiB,CAAC,EAAE;YAC1F,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,EACF,kBAAkB,CACnB,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,QAAQ,CACZ,MAAc,EACd,iBAAyB,EACzB,UAAuC,EAAE;QAEzC,OAAO,IAAI,CAAC,KAAK,CACf,+BAAmB,EACnB,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACpC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,MAAM,CAAC,WAAW;YAClE,IAAI,EAAE,EAAE,iBAAiB,EAAE;YAC3B,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,6BAA6B,QAAQ,CAAC,MAAM,CAAC,EAAE;YACzF,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,EACF,kBAAkB,CACnB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CACd,OAAuC,EACvC,OAA0E;QAE1E,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CACtB,8CAAkC,EAClC,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACpC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,iCAAiC;YACvC,IAAI,EAAE,OAAO;YACb,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,EACF,uCAAuC,CACxC,CAAC;QACF,OAAO,KAAK,CAAC,WAAW,CAAC;IAC3B,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,IAAI,CACR,MAAc,EACd,UAAyC,EACzC,UAAuC,EAAE;QAEzC,OAAO,IAAI,CAAC,KAAK,CACf,qCAAyB,EACzB,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACpC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,uBAAuB,kBAAkB,CAAC,MAAM,CAAC,UAAU;YACjE,IAAI,EAAE,UAAU;YAChB,cAAc,EACZ,OAAO,CAAC,cAAc,IAAI,yBAAyB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,gBAAgB,CAAC,EAAE;YACpG,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,EACF,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,KAAK,CAAC,kBAAqC,EAAE,UAAoC,EAAE;QACvF,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAClD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,qCAAyB,EACzB,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACpC,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,sCAAsC,QAAQ,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;YACxF,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,EACF,gCAAgC,CACjC,CAAC;QACF,OAAO,QAAQ,CAAC,KAAK,CAAC;IACxB,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,SAAS,CAAC,iBAAyB,EAAE,UAAoC,EAAE;QAC/E,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,mCAAuB,EACvB,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACpC,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,kCAAkC,kBAAkB,CAAC,iBAAiB,CAAC,QAAQ;YACrF,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,EACF,2BAA2B,CAC5B,CAAC;QACF,OAAO,QAAQ,CAAC,KAAK,CAAC;IACxB,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,OAAO,CACX,gBAAwB,EACxB,UAAoC,EAAE;QAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,wCAA4B,EAC5B,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAU;YACpC,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,kCAAkC,kBAAkB,CAAC,gBAAgB,CAAC,UAAU;YACtF,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,EACF,kCAAkC,CACnC,CAAC;QACF,OAAO,QAAQ,CAAC,OAAO,CAAC;IAC1B,CAAC;IAEO,KAAK,CAAsB,MAAS,EAAE,QAAiB,EAAE,IAAY;QAC3E,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,qCAAyB,CAAC,6BAA6B,IAAI,kCAAkC,EAAE;gBACvG,SAAS,EAAE,KAAK;gBAChB,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;CACF;AAhJD,wCAgJC"}

package/dist/credential.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+/** The credential CrowdSource issues, parsed. */
+export interface ServiceCredential {
+    /** The application this credential belongs to. The tenant, and its only source. */
+    readonly applicationId: string;
+    readonly credentialId: string;
+    /**
+     * The bearer token the API authenticates — `<credentialId>.<secret>`, exactly
+     * what `credential.service.ts` parses. The secret is never held on its own,
+     * so nothing in this client can log or serialise it by touching a field.
+     */
+    readonly bearerToken: string;
+}
+/** The three values `issueApplicationCredential` returns, as one opaque key. */
+export declare function formatServiceKey(issued: {
+    applicationId: string;
+    credentialId: string;
+    secret: string;
+}): string;
+/**
+ * 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 declare function parseServiceKey(serviceKey: string): ServiceCredential;
+//# sourceMappingURL=credential.d.ts.map

package/dist/credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.d.ts","sourceRoot":"","sources":["../src/credential.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAQH,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAET;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,iBAAiB,CAgCrE"}

package/dist/credential.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatServiceKey = formatServiceKey;
+exports.parseServiceKey = parseServiceKey;
+const contracts_1 = require("@crowdsource.you/contracts");
+const errors_js_1 = require("./errors.js");
+const SERVICE_KEY_SEPARATOR = ':';
+/** The three values `issueApplicationCredential` returns, as one opaque key. */
+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.
+ */
+function parseServiceKey(serviceKey) {
+    const trimmed = serviceKey.trim();
+    if (!trimmed) {
+        throw new errors_js_1.CrowdSourceConfigurationError('The CrowdSource service key is empty.');
+    }
+    const parts = trimmed.split(SERVICE_KEY_SEPARATOR);
+    if (parts.length !== 3) {
+        throw new errors_js_1.CrowdSourceConfigurationError(`A CrowdSource service key is three colon-separated parts (applicationId:credentialId:secret); this one has ${parts.length}.`);
+    }
+    const [applicationId, credentialId, secret] = parts;
+    if (!contracts_1.IdentifierSchema.safeParse(applicationId).success) {
+        throw new errors_js_1.CrowdSourceConfigurationError('The first part of a CrowdSource service key must be the applicationId it was issued for.');
+    }
+    if (!contracts_1.IdentifierSchema.safeParse(credentialId).success) {
+        throw new errors_js_1.CrowdSourceConfigurationError('The second part of a CrowdSource service key must be the credentialId it was issued for.');
+    }
+    if (!secret) {
+        throw new errors_js_1.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/credential.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential.js","sourceRoot":"","sources":["../src/credential.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;AAsBH,4CAMC;AASD,0CAgCC;AAnED,0DAA8D;AAE9D,2CAA4D;AAE5D,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAelC,gFAAgF;AAChF,SAAgB,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,SAAgB,eAAe,CAAC,UAAkB;IAChD,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,yCAA6B,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,yCAA6B,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,4BAAgB,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE,CAAC;QACvD,MAAM,IAAI,yCAA6B,CACrC,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,4BAAgB,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC;QACtD,MAAM,IAAI,yCAA6B,CACrC,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,yCAA6B,CACrC,4EAA4E,CAC7E,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,GAAG,YAAY,IAAI,MAAM,EAAE,EAAE,CAAC;AACnF,CAAC"}