@rightkit/social-ui 0.0.0-stage → 0.1.0

package/dist/data/engine/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A read the engine cannot answer yet, because the method or the field does not exist in the engine.
+ * Screens show their load error state for it. The message is kept for logs and tests.
+ */
+export declare class EngineUnavailableError extends Error {
+    readonly code: "engine_unavailable";
+    constructor(message: string);
+}
+/** A read the engine answered with an error, or an engine reply the desktop cannot map. */
+export declare class EngineReadError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/dist/data/engine/errors.js

@@ -0,0 +1,21 @@
+// Errors the engine data source throws from reads. Writes never throw: they return a Result.
+/**
+ * A read the engine cannot answer yet, because the method or the field does not exist in the engine.
+ * Screens show their load error state for it. The message is kept for logs and tests.
+ */
+export class EngineUnavailableError extends Error {
+    code = "engine_unavailable";
+    constructor(message) {
+        super(message);
+        this.name = "EngineUnavailableError";
+    }
+}
+/** A read the engine answered with an error, or an engine reply the desktop cannot map. */
+export class EngineReadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "EngineReadError";
+        this.code = code;
+    }
+}

package/dist/data/engine/mapping.d.ts

@@ -0,0 +1,172 @@
+import type { Account, FailureItem, ManualDraft, PublishJob, PublishProgress, PublishJobRecord, RejectReason, HeartbeatStatus, RestoreReceiptList, InboxEvent, InboxRaw, InboxStats, PublishNextView, PublishQuota, UnreadableRow } from "../types.js";
+import type { OptimiseProposal, SpendAllowance, SpendPrice, SpendReport } from "../types.js";
+import type { Campaign, CampaignAttribution, ChannelLink, HookTestSet, TrackedLink, ContentDetail, ContentExperimentSummary, ContentRecord, ContentVariant, DigestApplication, ResearchDigest, BriefSummary, DeliveryEnvelope, DispatchAttempt, GateCheck, GatePolicy, GateRecord, JsonValue, OutgoingBrief, OutgoingBriefDetail, ChannelMemoryDetail, ChannelMemoryRevision, ProofRecord, BriefVariant, TypedBrief, AnalyticsObservation, AnalyticsPost, MetricImport } from "../types.js";
+import { EngineReadError } from "./errors.js";
+import type { EngineAccount, EngineCampaign, EngineDraft, EngineEntry, EngineHookTestSet, EngineLinkAttribution, EngineOptimiseProposal, EnginePublishJob, EngineInboxEvent, EngineInboxGet, EngineInboxStats, EnginePublishNext, EnginePublishQuota, EngineScope, EngineSpendAllowance, EngineSpendPrice, EngineSpendReport, EngineTrackedLink, EngineDigestApplication, EngineDigestRecord, EngineContentExperimentSummary, EngineContentGet, EngineContentRecord, EngineContentVariant, EngineGatePolicy, EngineGateCheck, EngineGateRecord, EngineBriefOut, EngineDeliveryRecord, EngineDispatchAttempt, EngineMemoryGet, EngineMemoryRevisionRow, EngineProofRow, EngineBriefVariant, EngineTypedBrief, EngineAnalyticsObservation, EngineAnalyticsSummary, EngineMetricImportRecord, EngineHeartbeatStatus, EngineRestoreReceiptList } from "./protocol.js";
+/** The desktop's account key: the engine scope (venture, channel, account). */
+export declare function accountKey(scope: EngineScope): string;
+/** The desktop's job id: the account key plus the engine entry id. */
+export declare function jobKey(scope: EngineScope, entryId: string): string;
+/** Reverses jobKey. Null when the id is not one this data source issued. */
+export declare function parseJobKey(id: string): {
+    scope: EngineScope;
+    entryId: string;
+} | null;
+/**
+ * The desktop's account id: the engine scope plus the platform. The engine keys an account by scope
+ * and platform. Jobs carry only the scope (`accountKey`), so a job does not name one of its
+ * channel's accounts (see "Engine gaps" in the design doc).
+ */
+export declare function accountId(scope: EngineScope, platform: string): string;
+/** Reverses accountId. Null when the id is not one this data source issued. */
+export declare function parseAccountId(id: string): {
+    scope: EngineScope;
+    platform: string;
+} | null;
+/** The desktop's draft id: the engine scope plus the engine draft id. */
+export declare function draftKey(scope: EngineScope, draftId: string): string;
+/** Reverses draftKey. Null when the id is not one this data source issued. */
+export declare function parseDraftKey(id: string): {
+    scope: EngineScope;
+    draftId: string;
+} | null;
+/** An engine draft as the desktop's ManualDraft. A state or kind the desktop does not show is an engine_mapping error. */
+export declare function draftOf(engine: EngineDraft): ManualDraft;
+/** The engine's instant form: YYYY-MM-DDTHH:MM:SSZ (no milliseconds). */
+export declare function engineInstant(iso: string): string;
+/**
+ * FNV-1a over the caption's UTF-16 code units. The engine stores no caption digest, so this is a
+ * display fingerprint computed here. It is not the daemon's SHA-256 and cannot be compared with it.
+ */
+export declare function captionFingerprint(caption: string): string;
+export declare function encodeRejection(code: RejectReason, note: string): string;
+export declare function parseRejection(text: string): {
+    reason: RejectReason;
+    note: string | null;
+};
+/**
+ * One engine entry as the operator's PublishJob. Fields the engine does not hold are set as the
+ * design doc's "Engine gaps" section records: null or empty means "not reported", not "none".
+ */
+export declare function entryToJob(entry: EngineEntry): PublishJob;
+/**
+ * An engine account the desktop cannot map yet: its platform, or a state it does not show. It is
+ * kept with its typed error so the list is not silently shorter than the engine's.
+ */
+export interface UnmappedAccount {
+    /** The desktop account id the account would have had (accountId). */
+    id: string;
+    platform: string;
+    error: EngineReadError;
+}
+/**
+ * One engine account as the operator's Account. `nowUtc` is the caller's clock (the data source
+ * passes its own); this function reads no clock. A cooldown reads as active only while it is after
+ * `nowUtc`.
+ */
+export declare function accountOf(engine: EngineAccount, nowUtc: string): Account;
+/** One engine publish job as the desktop's progress view. Throws on a state the desktop does not show. */
+export declare function publishProgressOf(engine: EnginePublishJob): PublishProgress;
+/**
+ * The publish job for one calendar entry at its current revision, or null when there is none. A job
+ * for an older revision is not shown: the entry changed after that job was approved.
+ */
+export declare function publishProgressFor(jobs: readonly EnginePublishJob[], entry: EngineEntry): PublishProgress | null;
+/**
+ * A failure row for a publish job that needs the operator: failed, outcome_unknown, or cancelled with
+ * a reason. Queued, running, waiting and published jobs need no failure row (null).
+ */
+export declare function publishFailureOf(engine: EnginePublishJob): FailureItem | null;
+/** One engine publish job as the desktop's read-only row. publishProgressOf refuses a state the desktop does not show. */
+export declare function publishJobRecordOf(engine: EnginePublishJob): PublishJobRecord;
+/** The scope a suggestion or spend id names. Null when the id is not one this data source issued. */
+export declare function parseScopeKey(id: string): EngineScope | null;
+/** One optimise proposal as the desktop's OptimiseProposal. Only the remake rule and the three states are shown. */
+export declare function proposalOf(engine: EngineOptimiseProposal): OptimiseProposal;
+export declare function allowanceOf(engine: EngineSpendAllowance): SpendAllowance;
+export declare function spendReportOf(engine: EngineSpendReport): SpendReport;
+export declare function priceOf(engine: EngineSpendPrice): SpendPrice;
+/** One engine campaign as the desktop's Campaign. */
+export declare function campaignOf(engine: EngineCampaign): Campaign;
+/** One engine tracked link as the desktop's TrackedLink. The UTM parts and final URL are shown as stored. */
+export declare function linkOf(engine: EngineTrackedLink): TrackedLink;
+/**
+ * The visit counts of one campaign. The engine's total must equal the sum of its rows; a mismatch is
+ * refused, not shown.
+ */
+export declare function attributionOf(engine: EngineLinkAttribution): CampaignAttribution;
+/**
+ * The links of one campaign, each with the campaign's name and its count from the attribution reply of the same
+ * campaign. A link the attribution reply does not list has no count (null), never a zero.
+ */
+export declare function channelLinksOf(campaignName: string, links: readonly EngineTrackedLink[], attribution: EngineLinkAttribution): ChannelLink[];
+/**
+ * One engine hook test set as the desktop's HookTestSet. A decided set must name its winner and its
+ * decision instant; a set missing either is a mapping error.
+ */
+export declare function hookTestOf(engine: EngineHookTestSet): HookTestSet;
+/** One stored digest as the desktop's ResearchDigest. The id is the engine's digest id, within its scope. */
+export declare function digestOf(engine: EngineDigestRecord): ResearchDigest;
+/** One applied digest entry as the desktop's DigestApplication. The entry's scope comes from the digest.applied reply. */
+export declare function digestApplicationOf(engine: EngineDigestApplication, scope: EngineScope): DigestApplication;
+/** One stored content record as the desktop's ContentRecord. The state is the engine's derived state. */
+export declare function contentRecordOf(engine: EngineContentRecord): ContentRecord;
+/** One content variant as the desktop's ContentVariant. */
+export declare function contentVariantOf(engine: EngineContentVariant): ContentVariant;
+/** The record and variants of one content.get reply, as the desktop's ContentDetail. */
+export declare function contentDetailOf(engine: EngineContentGet): ContentDetail;
+/** The variant comparison of one content.experiment_summary reply. The verdict is checked, never reworded. */
+export declare function experimentSummaryOf(engine: EngineContentExperimentSummary): ContentExperimentSummary;
+/** The latest policy revision as the desktop's GatePolicy. */
+export declare function gatePolicyOf(engine: EngineGatePolicy): GatePolicy;
+/** One gate.check reply as the desktop's GateCheck. The desktop never asks the engine to record, so nothing is stored. */
+export declare function gateCheckOf(engine: EngineGateCheck): GateCheck;
+/** One stored verdict record. The scope is the one the read was made in, because the record carries none. */
+export declare function gateRecordOf(engine: EngineGateRecord, scopeId: string): GateRecord;
+/** The fields of a brief document the desktop shows. Anything the document lacks stays null or empty. */
+export declare function briefSummaryOf(document: JsonValue): BriefSummary;
+/** One outgoing brief as the list shows it. The document is left out of the list. */
+export declare function briefOf(engine: EngineBriefOut): OutgoingBrief;
+/** One outgoing brief with its summary and the document as stored. */
+export declare function briefDetailOf(engine: EngineBriefOut): OutgoingBriefDetail;
+/** One accepted delivery envelope as the desktop's DeliveryEnvelope. */
+export declare function deliveryOf(engine: EngineDeliveryRecord): DeliveryEnvelope;
+/** One dispatch attempt. The message and stderr tail are read from the engine's detail object when present. */
+export declare function dispatchAttemptOf(engine: EngineDispatchAttempt, scopeId: string): DispatchAttempt;
+/** One stored memory revision without its document. The scope is the one the read was made in. */
+export declare function memoryRevisionOf(engine: EngineMemoryRevisionRow, scopeId: string): ChannelMemoryRevision;
+/** The latest memory revision with its document. A document that is not a JSON object is a mapping error. */
+export declare function memoryDetailOf(engine: EngineMemoryGet): ChannelMemoryDetail;
+/** One proof row. The value is kept as the exact decimal text the engine sent; it is never parsed. */
+export declare function proofOf(engine: EngineProofRow): ProofRecord;
+/** One stored typed brief as the desktop's TypedBrief. An explainer with no beats is a mapping error. */
+export declare function typedBriefOf(engine: EngineTypedBrief): TypedBrief;
+/** One platform variant as the desktop's BriefVariant. The link is kept as given; no slot is re-derived. */
+export declare function briefVariantOf(engine: EngineBriefVariant): BriefVariant;
+/**
+ * The published posts of one scope, from analytics.summary. The summary names no source: a metric with an
+ * import id is a manual row, and one without is an API row.
+ */
+export declare function analyticsPostsOf(engine: EngineAnalyticsSummary): AnalyticsPost[];
+/** One stored observation, from analytics.list. The scope is the one the read was made in. */
+export declare function analyticsObservationOf(engine: EngineAnalyticsObservation, scopeId: string): AnalyticsObservation;
+/** One committed manual import. Only the manual_export source is shown; any other source is a mapping error. */
+export declare function metricImportOf(engine: EngineMetricImportRecord): MetricImport;
+/** The heartbeat status as the desktop's HeartbeatStatus: one record, no per-source list. */
+export declare function heartbeatStatusOf(engine: EngineHeartbeatStatus): HeartbeatStatus;
+/** The restore receipts as the desktop's RestoreReceiptList, newest first as the engine sends them. */
+export declare function restoreReceiptListOf(engine: EngineRestoreReceiptList): RestoreReceiptList;
+/** A value as pretty printed JSON text. Used for raw rows and raw event items. */
+export declare function rawTextOf(value: unknown): string;
+/** Maps one row. A row whose mapping throws is kept unread, with the reason and its raw JSON. It is never dropped. */
+export declare function rowOf<T>(raw: unknown, map: () => T): T | UnreadableRow;
+/** One inbox event. An unknown kind or state is a mapping error, so the row is kept unread (see rowOf). */
+export declare function inboxEventOf(engine: EngineInboxEvent): InboxEvent;
+/** The raw item JSON of one event, shown as text. */
+export declare function inboxRawOf(engine: EngineInboxGet): InboxRaw;
+/** The inbox counts as the engine stores them. Each group is kept, even one whose count cannot be read. */
+export declare function inboxStatsOf(engine: EngineInboxStats): InboxStats;
+/** publish.next as the desktop's view. Every row is kept: a row it cannot read is an UnreadableRow. */
+export declare function publishNextOf(engine: EnginePublishNext): PublishNextView;
+/** One account's pacing as stored. The limits are the stored ones, or the host app defaults when opted_in is false. */
+export declare function publishQuotaOf(engine: EnginePublishQuota): PublishQuota;