@cogitator-ai/channels 0.9.2 → 0.10.0

package/dist/channels/threads/index.js

@@ -0,0 +1,6 @@
+export { ThreadsAccount } from './account.js';
+export { THREADS_API, ThreadsClient, threadsErrorCode } from './client.js';
+export { THREADS_LIMITS, ThreadsFeed, threadsFeed } from './feed.js';
+export { ThreadsTokenManager } from './token.js';
+export { ThreadsChannel, threadsChannel, verifyThreadsSignature, } from './channel.js';
+//# sourceMappingURL=index.js.map

package/dist/channels/threads/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/channels/threads/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA6B,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAsB,MAAM,UAAU,CAAC;AAC5F,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,WAAW,EAA0B,MAAM,QAAQ,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAA4B,MAAM,SAAS,CAAC;AACxE,OAAO,EACL,cAAc,EACd,cAAc,EACd,sBAAsB,GAKvB,MAAM,WAAW,CAAC"}

package/dist/channels/threads/token.d.ts

@@ -0,0 +1,51 @@
+import type { StoredToken, TokenStore } from '@cogitator-ai/types';
+import type { ThreadsClient } from './client.js';
+export interface ThreadsTokenOptions {
+    /** A long-lived token to start from when the store holds none. */
+    accessToken?: string;
+    /** When `accessToken` expires, where known. Otherwise the first renewal finds out. */
+    accessTokenExpiresAt?: Date | number;
+    /** Where the token is kept and renewed (default in memory). */
+    store?: TokenStore;
+    /** The token's key in the store (default `threads`). */
+    storeKey?: string;
+    /** How long before it expires the token is renewed (default seven days). */
+    renewBefore?: number;
+    /** Called with the new token after each renewal. */
+    onTokenRenewed?: (token: StoredToken) => void | Promise<void>;
+    now?: () => number;
+}
+/**
+ * A Threads long-lived token kept fresh. Threads renews a token that is at
+ * least a day old and not yet expired, for sixty days. One left alone
+ * expires and cannot be renewed. The manager renews it `renewBefore` its
+ * end, checks daily once started, and before each use. A token whose expiry
+ * is unknown is renewed at the first chance, which reveals it. Calls made at
+ * the same time share one renewal. Before renewing, the manager rereads the
+ * store, so a token another process renewed is used as it is. Two processes
+ * renewing at the same moment both get valid tokens.
+ */
+export declare class ThreadsTokenManager {
+    private readonly client;
+    private readonly options;
+    private readonly store;
+    private readonly key;
+    private readonly renewBefore;
+    private readonly now;
+    private nextAttemptAt;
+    private renewing?;
+    private timer?;
+    constructor(client: ThreadsClient, options: ThreadsTokenOptions);
+    /** A token to call the API with, renewed first when it is due. */
+    token(): Promise<string>;
+    /** Renews the token now, whatever its age. */
+    renew(): Promise<StoredToken>;
+    private renewOnce;
+    /** Checks the token every day until `stop()`. */
+    start(): void;
+    stop(): void;
+    private current;
+    private due;
+    private doRenew;
+}
+//# sourceMappingURL=token.d.ts.map

package/dist/channels/threads/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../../src/channels/threads/token.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAK9C,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,oBAAoB,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACrC,+DAA+D;IAC/D,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAmB;IAU5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAuB;IACxC,OAAO,CAAC,KAAK,CAAC,CAAiC;gBAG5B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,mBAAmB;IAQ/C,kEAAkE;IAC5D,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAoB9B,8CAA8C;IAC9C,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAI7B,OAAO,CAAC,SAAS;IAOjB,iDAAiD;IACjD,KAAK,IAAI,IAAI;IAUb,IAAI,IAAI,IAAI;YAKE,OAAO;IAsBrB,OAAO,CAAC,GAAG;YAMG,OAAO;CA4BtB"}

package/dist/channels/threads/token.js

@@ -0,0 +1,128 @@
+import { FeedError } from '../../feeds/errors.js';
+import { MemoryTokenStore } from '../../feeds/token-store.js';
+const DAY = 24 * 60 * 60 * 1000;
+const HOUR = 60 * 60 * 1000;
+/**
+ * A Threads long-lived token kept fresh. Threads renews a token that is at
+ * least a day old and not yet expired, for sixty days. One left alone
+ * expires and cannot be renewed. The manager renews it `renewBefore` its
+ * end, checks daily once started, and before each use. A token whose expiry
+ * is unknown is renewed at the first chance, which reveals it. Calls made at
+ * the same time share one renewal. Before renewing, the manager rereads the
+ * store, so a token another process renewed is used as it is. Two processes
+ * renewing at the same moment both get valid tokens.
+ */
+export class ThreadsTokenManager {
+    client;
+    options;
+    store;
+    key;
+    renewBefore;
+    now;
+    nextAttemptAt = 0;
+    renewing;
+    timer;
+    constructor(client, options) {
+        this.client = client;
+        this.options = options;
+        this.store = options.store ?? new MemoryTokenStore();
+        this.key = options.storeKey ?? 'threads';
+        this.renewBefore = options.renewBefore ?? 7 * DAY;
+        this.now = options.now ?? Date.now;
+    }
+    /** A token to call the API with, renewed first when it is due. */
+    async token() {
+        const current = await this.current();
+        if (current.expiresAt !== undefined && current.expiresAt <= this.now()) {
+            throw new FeedError('threads', 'token_expired', `The Threads token expired on ${new Date(current.expiresAt).toISOString()}: sign in again for a new long-lived token`);
+        }
+        if (this.due(current)) {
+            try {
+                return (await this.renewOnce(false)).value;
+            }
+            catch (error) {
+                if (error instanceof FeedError && error.code === 'token_expired')
+                    throw error;
+                console.warn('[threads] Could not renew the token, using the current one:', error);
+            }
+        }
+        return current.value;
+    }
+    /** Renews the token now, whatever its age. */
+    renew() {
+        return this.renewOnce(true);
+    }
+    renewOnce(force) {
+        this.renewing ??= this.doRenew(force).finally(() => {
+            this.renewing = undefined;
+        });
+        return this.renewing;
+    }
+    /** Checks the token every day until `stop()`. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.token().catch((error) => console.error('[threads] The daily token check failed:', error));
+        }, DAY);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    async current() {
+        const stored = await this.store.get(this.key);
+        if (stored)
+            return stored;
+        if (!this.options.accessToken) {
+            throw new FeedError('threads', 'auth', 'No Threads token: pass accessToken or put one in the token store');
+        }
+        const expiresAt = this.options.accessTokenExpiresAt;
+        const seeded = {
+            value: this.options.accessToken,
+            issuedAt: this.now(),
+            ...(expiresAt !== undefined && {
+                expiresAt: typeof expiresAt === 'number' ? expiresAt : expiresAt.getTime(),
+            }),
+        };
+        await this.store.set(this.key, seeded);
+        return seeded;
+    }
+    due(token) {
+        if (this.now() < this.nextAttemptAt)
+            return false;
+        if (token.expiresAt === undefined)
+            return true;
+        return token.expiresAt - this.now() <= this.renewBefore && this.now() - token.issuedAt >= DAY;
+    }
+    async doRenew(force) {
+        const latest = await this.current();
+        if (!force && !this.due(latest))
+            return latest;
+        try {
+            const response = await this.client.get('refresh_access_token', latest.value, { grant_type: 'th_refresh_token' });
+            const now = this.now();
+            const renewed = {
+                value: response.access_token,
+                issuedAt: now,
+                ...(response.expires_in !== undefined && { expiresAt: now + response.expires_in * 1000 }),
+            };
+            await this.store.set(this.key, renewed);
+            this.nextAttemptAt = 0;
+            try {
+                await this.options.onTokenRenewed?.(renewed);
+            }
+            catch (error) {
+                console.error('[threads] onTokenRenewed failed:', error);
+            }
+            return renewed;
+        }
+        catch (error) {
+            this.nextAttemptAt = this.now() + HOUR;
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/channels/threads/token.js.map

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

package/dist/feeds/attachments.d.ts

@@ -0,0 +1,15 @@
+import type { Attachment } from '@cogitator-ai/types';
+/**
+ * The bytes of an attachment: its buffer, or its URL downloaded. Fails with
+ * `invalid_post` when it is over `maxBytes`, without reading past the limit,
+ * or when the URL does not serve it, and with `unavailable` (or
+ * `rate_limited`) when its host fails for now, so the post is tried again.
+ */
+export declare function attachmentBytes(feed: string, attachment: Attachment, options: {
+    maxBytes: number;
+    fetch?: typeof fetch;
+    what: string;
+}): Promise<Uint8Array>;
+/** Fails with `invalid_post` unless the attachment is an image. */
+export declare function assertImage(feed: string, attachment: Attachment, what: string): void;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/feeds/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../src/feeds/attachments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChE,OAAO,CAAC,UAAU,CAAC,CAqFrB;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAQpF"}

package/dist/feeds/attachments.js

@@ -0,0 +1,85 @@
+import { FeedError, retryAfterOf } from './errors.js';
+/**
+ * The bytes of an attachment: its buffer, or its URL downloaded. Fails with
+ * `invalid_post` when it is over `maxBytes`, without reading past the limit,
+ * or when the URL does not serve it, and with `unavailable` (or
+ * `rate_limited`) when its host fails for now, so the post is tried again.
+ */
+export async function attachmentBytes(feed, attachment, options) {
+    const tooLarge = (size) => new FeedError(feed, 'invalid_post', `${options.what} is ${size} bytes, the feed takes up to ${options.maxBytes}`);
+    if (attachment.buffer) {
+        if (attachment.buffer.byteLength > options.maxBytes)
+            throw tooLarge(attachment.buffer.byteLength);
+        return attachment.buffer;
+    }
+    if (!attachment.url) {
+        throw new FeedError(feed, 'invalid_post', `${options.what} has neither a buffer nor a url`);
+    }
+    const unreachable = (error) => new FeedError(feed, 'unavailable', `Could not download ${options.what} from ${attachment.url}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    let response;
+    try {
+        response = await (options.fetch ?? fetch)(attachment.url);
+    }
+    catch (error) {
+        throw unreachable(error);
+    }
+    if (!response.ok) {
+        const { status } = response;
+        const code = status === 429
+            ? 'rate_limited'
+            : status === 408 || status >= 500
+                ? 'unavailable'
+                : 'invalid_post';
+        const retryAfter = retryAfterOf(response.headers);
+        await response.body?.cancel().catch(() => { });
+        throw new FeedError(feed, code, `Could not download ${options.what} from ${attachment.url}: HTTP ${status}`, { status, ...(retryAfter !== undefined && { retryAfter }) });
+    }
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > options.maxBytes) {
+        await response.body?.cancel();
+        throw tooLarge(declared);
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+        try {
+            return new Uint8Array(await response.arrayBuffer());
+        }
+        catch (error) {
+            throw unreachable(error);
+        }
+    }
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        let chunk;
+        try {
+            chunk = await reader.read();
+        }
+        catch (error) {
+            throw unreachable(error);
+        }
+        const { done, value } = chunk;
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > options.maxBytes) {
+            await reader.cancel();
+            throw tooLarge(size);
+        }
+        chunks.push(value);
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+/** Fails with `invalid_post` unless the attachment is an image. */
+export function assertImage(feed, attachment, what) {
+    if (attachment.type !== 'image' || !attachment.mimeType.startsWith('image/')) {
+        throw new FeedError(feed, 'invalid_post', `${what} must be an image, got ${attachment.type} (${attachment.mimeType})`);
+    }
+}
+//# sourceMappingURL=attachments.js.map

package/dist/feeds/attachments.js.map

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

package/dist/feeds/errors.d.ts

@@ -0,0 +1,39 @@
+export type FeedErrorCode = 
+/** The credentials are wrong or lack a permission. */
+'auth'
+/** The token or session expired and cannot be renewed. */
+ | 'token_expired'
+/** Too many requests: try again after `retryAfter`. */
+ | 'rate_limited'
+/** The account used up its publishing quota for now. */
+ | 'quota_exceeded'
+/** The post breaks a rule of the feed: too long, too many links, a bad tag or image. */
+ | 'invalid_post'
+/** The post or account it refers to does not exist. */
+ | 'not_found'
+/** The feed failed or did not answer: try again. */
+ | 'unavailable' | 'unknown';
+/** A failure of a feed, with whether and when trying again can help. */
+export declare class FeedError extends Error {
+    readonly feed: string;
+    readonly code: FeedErrorCode;
+    /** The HTTP status, where the feed answered with one. */
+    readonly status?: number;
+    /** How long to wait before trying again, in ms, where the feed said. */
+    readonly retryAfter?: number;
+    constructor(feed: string, code: FeedErrorCode, message: string, options?: {
+        status?: number;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+    /** Whether publishing again later can succeed. */
+    get retryable(): boolean;
+}
+/** The error code an HTTP status means, where the body says nothing more precise. */
+export declare function feedErrorCode(status: number): FeedErrorCode;
+/**
+ * How long a `Retry-After` header (seconds or an HTTP date) or a
+ * `ratelimit-reset` header (epoch seconds) asks to wait, in ms.
+ */
+export declare function retryAfterOf(headers: Headers, now?: number): number | undefined;
+//# sourceMappingURL=errors.d.ts.map

package/dist/feeds/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/feeds/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa;AACvB,sDAAsD;AACpD,MAAM;AACR,0DAA0D;GACxD,eAAe;AACjB,uDAAuD;GACrD,cAAc;AAChB,wDAAwD;GACtD,gBAAgB;AAClB,wFAAwF;GACtF,cAAc;AAChB,uDAAuD;GACrD,WAAW;AACb,oDAAoD;GAClD,aAAa,GACb,SAAS,CAAC;AAQd,wEAAwE;AACxE,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;gBAG3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;IAUzE,kDAAkD;IAClD,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAO3D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAWnF"}

package/dist/feeds/errors.js

@@ -0,0 +1,62 @@
+const RETRYABLE = new Set([
+    'rate_limited',
+    'quota_exceeded',
+    'unavailable',
+]);
+/** A failure of a feed, with whether and when trying again can help. */
+export class FeedError extends Error {
+    feed;
+    code;
+    /** The HTTP status, where the feed answered with one. */
+    status;
+    /** How long to wait before trying again, in ms, where the feed said. */
+    retryAfter;
+    constructor(feed, code, message, options = {}) {
+        super(`[${feed}] ${message}`, { cause: options.cause });
+        this.name = 'FeedError';
+        this.feed = feed;
+        this.code = code;
+        if (options.status !== undefined)
+            this.status = options.status;
+        if (options.retryAfter !== undefined)
+            this.retryAfter = options.retryAfter;
+    }
+    /** Whether publishing again later can succeed. */
+    get retryable() {
+        return RETRYABLE.has(this.code);
+    }
+}
+/** The error code an HTTP status means, where the body says nothing more precise. */
+export function feedErrorCode(status) {
+    if (status === 401 || status === 403)
+        return 'auth';
+    if (status === 404)
+        return 'not_found';
+    if (status === 429)
+        return 'rate_limited';
+    if (status === 400 || status === 413 || status === 422)
+        return 'invalid_post';
+    if (status >= 500)
+        return 'unavailable';
+    return 'unknown';
+}
+/**
+ * How long a `Retry-After` header (seconds or an HTTP date) or a
+ * `ratelimit-reset` header (epoch seconds) asks to wait, in ms.
+ */
+export function retryAfterOf(headers, now = Date.now()) {
+    const after = headers.get('retry-after');
+    if (after) {
+        const seconds = Number(after);
+        if (Number.isFinite(seconds))
+            return Math.max(0, seconds * 1000);
+        const date = Date.parse(after);
+        if (Number.isFinite(date))
+            return Math.max(0, date - now);
+    }
+    const reset = Number(headers.get('ratelimit-reset'));
+    if (Number.isFinite(reset) && reset > 0)
+        return Math.max(0, reset * 1000 - now);
+    return undefined;
+}
+//# sourceMappingURL=errors.js.map

package/dist/feeds/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/feeds/errors.ts"],"names":[],"mappings":"AAiBA,MAAM,SAAS,GAA+B,IAAI,GAAG,CAAC;IACpD,cAAc;IACd,gBAAgB;IAChB,aAAa;CACd,CAAC,CAAC;AAEH,wEAAwE;AACxE,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAS;IACb,IAAI,CAAgB;IAC7B,yDAAyD;IAChD,MAAM,CAAU;IACzB,wEAAwE;IAC/D,UAAU,CAAU;IAE7B,YACE,IAAY,EACZ,IAAmB,EACnB,OAAe,EACf,UAAqE,EAAE;QAEvE,KAAK,CAAC,IAAI,IAAI,KAAK,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC/D,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAC7E,CAAC;IAED,kDAAkD;IAClD,IAAI,SAAS;QACX,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,MAAM,CAAC;IACpD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,WAAW,CAAC;IACvC,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,cAAc,CAAC;IAC1C,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,cAAc,CAAC;IAC9E,IAAI,MAAM,IAAI,GAAG;QAAE,OAAO,aAAa,CAAC;IACxC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC9B,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,GAAG,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACrD,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC;IAChF,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/feeds/index.d.ts

@@ -0,0 +1,8 @@
+export { FeedError, feedErrorCode, retryAfterOf } from './errors.js';
+export type { FeedErrorCode } from './errors.js';
+export { FeedPublisher, type FeedFailedEvent, type FeedPublishedEvent, type FeedPublisherOptions, type FeedRetryOptions, type PublishOptions, type PublishOutcome, } from './publisher.js';
+export { FilePublishStore, MemoryPublishStore, PostgresPublishStore, decodeJob, encodeJob, isPending, nextDueAt, type FeedDelivery, type FilePublishStoreOptions, type JobClaim, type PostgresPublishStoreOptions, type PublishJob, type PublishStore, } from './publish-store.js';
+export { FileTokenStore, MemoryTokenStore, PostgresTokenStore, type FileTokenStoreOptions, type PostgresTokenStoreOptions, } from './token-store.js';
+export type { PgClient } from './storage.js';
+export { fitText, graphemeLength, graphemes, splitText, threadsLength, type TextMeasure, } from './text.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/feeds/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/feeds/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EACL,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,QAAQ,EACb,KAAK,2BAA2B,EAChC,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,GAC/B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EACL,OAAO,EACP,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,EACb,KAAK,WAAW,GACjB,MAAM,QAAQ,CAAC"}

package/dist/feeds/index.js

@@ -0,0 +1,6 @@
+export { FeedError, feedErrorCode, retryAfterOf } from './errors.js';
+export { FeedPublisher, } from './publisher.js';
+export { FilePublishStore, MemoryPublishStore, PostgresPublishStore, decodeJob, encodeJob, isPending, nextDueAt, } from './publish-store.js';
+export { FileTokenStore, MemoryTokenStore, PostgresTokenStore, } from './token-store.js';
+export { fitText, graphemeLength, graphemes, splitText, threadsLength, } from './text.js';
+//# sourceMappingURL=index.js.map

package/dist/feeds/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/feeds/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAElE,OAAO,EACL,aAAa,GAOd,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,GAOV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,GAGnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,OAAO,EACP,cAAc,EACd,SAAS,EACT,SAAS,EACT,aAAa,GAEd,MAAM,QAAQ,CAAC"}

package/dist/feeds/publish-store.d.ts

@@ -0,0 +1,148 @@
+import type { FeedPost } from '@cogitator-ai/types';
+import type { FeedErrorCode } from './errors.js';
+import { type PgClient } from './storage.js';
+/** How one feed of a job is doing. */
+export interface FeedDelivery {
+    feed: string;
+    status: 'pending' | 'published' | 'failed';
+    /** Attempts that could have published: a wait for a full quota is not one. */
+    attempts: number;
+    /** The feed's idempotency key, kept from before the first attempt until it is published. */
+    idempotencyKey?: string;
+    /** When to try next, in ms since the epoch, while pending. */
+    nextAttemptAt: number;
+    post?: {
+        id: string;
+        url: string;
+        publishedAt: number;
+    };
+    error?: {
+        code: FeedErrorCode;
+        message: string;
+    };
+}
+/** A post on its way to one or more feeds. */
+export interface PublishJob {
+    id: string;
+    /** Publishing twice with the same key publishes once. */
+    key?: string;
+    post: FeedPost;
+    createdAt: number;
+    deliveries: FeedDelivery[];
+}
+/** Whether a job still has a feed to publish to. */
+export declare function isPending(job: PublishJob): boolean;
+/** When the job's next pending delivery is due, or `undefined` when it is done. */
+export declare function nextDueAt(job: PublishJob): number | undefined;
+/** A worker's hold on a job: who holds it, and for how long a claim or an extension lasts. */
+export interface JobClaim {
+    owner: string;
+    /** In ms. */
+    ttl: number;
+}
+/**
+ * Where a publisher keeps its jobs, so scheduled and retried posts survive a
+ * restart. A worker claims a job before it publishes it, extends the claim
+ * while it works, and can save the job only while the claim is its own, so
+ * a worker that lost its claim never overwrites the one that took over.
+ */
+export interface PublishStore {
+    /** Adds `job`, unless one with the same key exists: that one is returned instead. */
+    add(job: PublishJob): Promise<PublishJob>;
+    get(id: string): Promise<PublishJob | undefined>;
+    /** Claims the job with the earliest delivery due by `now` that no one holds. */
+    claimNext(now: number, claim: JobClaim): Promise<PublishJob | undefined>;
+    /** Claims one job, `false` when someone holds it or it is missing. */
+    claim(id: string, claim: JobClaim): Promise<boolean>;
+    /** Extends `claim.owner`'s claim by `claim.ttl` from now, `false` when it lost it. */
+    extend(id: string, claim: JobClaim): Promise<boolean>;
+    /** Saves a job while `owner` holds it, `false` when the claim was lost and nothing was saved. */
+    save(job: PublishJob, owner: string): Promise<boolean>;
+    /** Releases `owner`'s claim on a job. */
+    release(id: string, owner: string): Promise<void>;
+    list(filter?: {
+        pending?: boolean;
+    }): Promise<PublishJob[]>;
+    /** Removes a job no worker holds, `false` when it is missing or held. */
+    remove(id: string): Promise<boolean>;
+}
+/** A job as JSON: attachment bytes become base64. */
+export declare function encodeJob(job: PublishJob): string;
+/** A job back from `encodeJob`. */
+export declare function decodeJob(json: string | unknown): PublishJob;
+/** Jobs in memory, for tests and a publisher that needs no restart safety. */
+export declare class MemoryPublishStore implements PublishStore {
+    private readonly jobs;
+    private readonly claims;
+    constructor(now?: () => number);
+    add(job: PublishJob): Promise<PublishJob>;
+    get(id: string): Promise<PublishJob | undefined>;
+    claimNext(now: number, claim: JobClaim): Promise<PublishJob | undefined>;
+    claim(id: string, claim: JobClaim): Promise<boolean>;
+    extend(id: string, claim: JobClaim): Promise<boolean>;
+    save(job: PublishJob, owner: string): Promise<boolean>;
+    release(id: string, owner: string): Promise<void>;
+    list(filter?: {
+        pending?: boolean;
+    }): Promise<PublishJob[]>;
+    remove(id: string): Promise<boolean>;
+}
+export interface FilePublishStoreOptions {
+    /** The directory with one JSON file per job (default `~/.cogitator/feed-jobs`). */
+    directory?: string;
+}
+/**
+ * Jobs as one JSON file each, written atomically, for a single publishing
+ * process: claims live in that process. Several workers need
+ * `PostgresPublishStore`.
+ */
+export declare class FilePublishStore implements PublishStore {
+    readonly directory: string;
+    private readonly queue;
+    private readonly claims;
+    constructor(options?: FilePublishStoreOptions, now?: () => number);
+    add(job: PublishJob): Promise<PublishJob>;
+    get(id: string): Promise<PublishJob | undefined>;
+    claimNext(now: number, claim: JobClaim): Promise<PublishJob | undefined>;
+    claim(id: string, claim: JobClaim): Promise<boolean>;
+    extend(id: string, claim: JobClaim): Promise<boolean>;
+    save(job: PublishJob, owner: string): Promise<boolean>;
+    release(id: string, owner: string): Promise<void>;
+    list(filter?: {
+        pending?: boolean;
+    }): Promise<PublishJob[]>;
+    remove(id: string): Promise<boolean>;
+    private fileOf;
+    private write;
+    private read;
+    private readAll;
+}
+export interface PostgresPublishStoreOptions {
+    client: PgClient;
+    /** Table name (default `cogitator_feed_jobs`), created on first use. */
+    table?: string;
+}
+/**
+ * Jobs in a Postgres table. Claims are leases on the database clock, taken
+ * with `FOR UPDATE SKIP LOCKED`, so several publishing workers split the due
+ * jobs between them, and a worker saves a job only while its lease holds.
+ */
+export declare class PostgresPublishStore implements PublishStore {
+    private readonly client;
+    private readonly table;
+    private ready?;
+    constructor(options: PostgresPublishStoreOptions);
+    add(job: PublishJob): Promise<PublishJob>;
+    get(id: string): Promise<PublishJob | undefined>;
+    claimNext(now: number, claim: JobClaim): Promise<PublishJob | undefined>;
+    claim(id: string, claim: JobClaim): Promise<boolean>;
+    extend(id: string, claim: JobClaim): Promise<boolean>;
+    save(job: PublishJob, owner: string): Promise<boolean>;
+    release(id: string, owner: string): Promise<void>;
+    list(filter?: {
+        pending?: boolean;
+    }): Promise<PublishJob[]>;
+    remove(id: string): Promise<boolean>;
+    private ensureTable;
+}
+//# sourceMappingURL=publish-store.d.ts.map

package/dist/feeds/publish-store.d.ts.map

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