@opencoredev/social-sdk 0.1.2 → 0.2.1

package/dist/core/concurrency.d.ts

@@ -0,0 +1,9 @@
+export interface ConcurrencyLimiterOptions {
+    readonly maxActive: number;
+    readonly maxQueued: number;
+    readonly backend?: string;
+}
+type Work<T> = () => Promise<T>;
+/** A client-owned FIFO budget for one backend instance. */
+export declare function createConcurrencyLimiter(options: ConcurrencyLimiterOptions): <T>(signal: AbortSignal | undefined, operation: string, work: Work<T>) => Promise<T>;
+export {};

package/dist/core/concurrency.js

@@ -0,0 +1,79 @@
+import { SocialError } from "./errors.js";
+/** A client-owned FIFO budget for one backend instance. */
+export function createConcurrencyLimiter(options) {
+    let active = 0;
+    const waiting = [];
+    async function acquire(signal, operation) {
+        if (signal?.aborted)
+            throw cancelled(operation);
+        if (active < options.maxActive) {
+            active += 1;
+            return release;
+        }
+        if (waiting.length >= options.maxQueued) {
+            throw saturated(operation, options.backend);
+        }
+        await new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                reject,
+                signal,
+                abort: () => {
+                    if (waiter.settled)
+                        return;
+                    waiter.settled = true;
+                    const index = waiting.indexOf(waiter);
+                    if (index !== -1)
+                        waiting.splice(index, 1);
+                    signal?.removeEventListener("abort", waiter.abort);
+                    reject(cancelled(operation));
+                },
+                settled: false,
+            };
+            waiting.push(waiter);
+            signal?.addEventListener("abort", waiter.abort, { once: true });
+        });
+        return release;
+        function release() {
+            const next = waiting.shift();
+            if (next === undefined) {
+                active -= 1;
+                return;
+            }
+            next.settled = true;
+            next.signal?.removeEventListener("abort", next.abort);
+            // Keep the slot reserved while the queued continuation resumes.
+            next.resolve();
+        }
+    }
+    return async function run(signal, operation, work) {
+        const release = await acquire(signal, operation);
+        try {
+            if (signal?.aborted)
+                throw cancelled(operation);
+            return await work();
+        }
+        finally {
+            release();
+        }
+    };
+}
+function cancelled(operation) {
+    return new SocialError({
+        code: "cancelled",
+        operation,
+        message: "The operation was cancelled while waiting for backend capacity",
+        retryDisposition: { kind: "never" },
+    });
+}
+function saturated(operation, backend) {
+    const options = {
+        code: "rate_limited",
+        operation,
+        message: "Backend concurrency queue is full",
+        retryDisposition: { kind: "after-delay", delayMs: 1000 },
+    };
+    if (backend !== undefined)
+        Object.assign(options, { backend: backend });
+    return new SocialError(options);
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,44 @@
+import type { ConnectedAccountRef, JsonObject, PreparationIssue, RetryDisposition } from "./types.js";
+export type SocialErrorCode = "invalid_config" | "invalid_input" | "unsupported_capability" | "missing_permission" | "reconnect_required" | "ineligible_account" | "approval_required" | "rate_limited" | "billing_required" | "media_error" | "not_found" | "gone" | "upstream_failure" | "ambiguous_outcome" | "cancelled" | "timeout" | "runtime_unsupported" | "unauthorized" | "idempotency_conflict";
+export interface SocialErrorOptions {
+    readonly code: SocialErrorCode;
+    readonly operation: string;
+    readonly message: string;
+    readonly backend?: string | undefined;
+    readonly account?: ConnectedAccountRef | undefined;
+    readonly issues?: readonly PreparationIssue[] | undefined;
+    readonly correlationId?: string | undefined;
+    readonly upstreamStatus?: number | undefined;
+    readonly upstreamCode?: string | undefined;
+    readonly retryDisposition?: RetryDisposition;
+    readonly details?: JsonObject | undefined;
+    readonly cause?: unknown;
+}
+export interface SerializedSocialError {
+    readonly name: "SocialError";
+    readonly code: SocialErrorCode;
+    readonly operation: string;
+    readonly message: string;
+    readonly backend?: string;
+    readonly account?: ConnectedAccountRef;
+    readonly issues?: readonly PreparationIssue[];
+    readonly correlationId?: string;
+    readonly upstreamStatus?: number;
+    readonly upstreamCode?: string;
+    readonly retryDisposition: RetryDisposition;
+    readonly details?: JsonObject;
+}
+export declare class SocialError extends Error {
+    readonly code: SocialErrorCode;
+    readonly operation: string;
+    readonly backend: string | undefined;
+    readonly account: ConnectedAccountRef | undefined;
+    readonly issues: readonly PreparationIssue[] | undefined;
+    readonly correlationId: string | undefined;
+    readonly upstreamStatus: number | undefined;
+    readonly upstreamCode: string | undefined;
+    readonly retryDisposition: RetryDisposition;
+    readonly details: JsonObject | undefined;
+    constructor(options: SocialErrorOptions);
+    toJSON(): SerializedSocialError;
+}

package/dist/core/errors.js

@@ -0,0 +1,50 @@
+export class SocialError extends Error {
+    code;
+    operation;
+    backend;
+    account;
+    issues;
+    correlationId;
+    upstreamStatus;
+    upstreamCode;
+    retryDisposition;
+    details;
+    constructor(options) {
+        super(options.message, { cause: options.cause });
+        this.name = "SocialError";
+        this.code = options.code;
+        this.operation = options.operation;
+        this.backend = options.backend;
+        this.account = options.account;
+        this.issues = options.issues;
+        this.correlationId = options.correlationId;
+        this.upstreamStatus = options.upstreamStatus;
+        this.upstreamCode = options.upstreamCode;
+        this.retryDisposition = options.retryDisposition ?? { kind: "never" };
+        this.details = options.details;
+    }
+    toJSON() {
+        const serialized = {
+            name: "SocialError",
+            code: this.code,
+            operation: this.operation,
+            message: this.message,
+            retryDisposition: this.retryDisposition,
+        };
+        if (this.backend !== undefined)
+            Object.assign(serialized, { backend: this.backend });
+        if (this.account !== undefined)
+            Object.assign(serialized, { account: this.account });
+        if (this.issues !== undefined)
+            Object.assign(serialized, { issues: this.issues });
+        if (this.correlationId !== undefined)
+            Object.assign(serialized, { correlationId: this.correlationId });
+        if (this.upstreamStatus !== undefined)
+            Object.assign(serialized, { upstreamStatus: this.upstreamStatus });
+        if (this.upstreamCode !== undefined)
+            Object.assign(serialized, { upstreamCode: this.upstreamCode });
+        if (this.details !== undefined)
+            Object.assign(serialized, { details: this.details });
+        return serialized;
+    }
+}

package/dist/core/idempotency.d.ts

@@ -0,0 +1,33 @@
+import type { DeliveryOutcome } from "./types.js";
+export interface IdempotencyClaimInput {
+    readonly scope: string;
+    readonly key: string;
+    readonly fingerprint: string;
+    readonly targetKeys: readonly string[];
+}
+export type IdempotencyClaim = {
+    readonly kind: "new" | "existing";
+    readonly claimId: string;
+    readonly outcomes: Readonly<Record<string, DeliveryOutcome>>;
+} | {
+    readonly kind: "conflict";
+};
+export interface IdempotencyStore {
+    /** Atomically creates or reads a logical operation claim. */
+    claim(input: IdempotencyClaimInput): Promise<IdempotencyClaim>;
+    /** Atomically persists one target outcome without replacing other target outcomes. */
+    saveOutcome(input: {
+        readonly claimId: string;
+        readonly targetKey: string;
+        readonly outcome: DeliveryOutcome;
+    }): Promise<void>;
+}
+export declare function stableSerialize(value: unknown): string;
+export declare function fingerprint(value: unknown): Promise<string>;
+export declare function deriveTargetIdempotencyKey(input: {
+    readonly logicalKey: string;
+    readonly scope?: string;
+    readonly backend: string;
+    readonly targetKey: string;
+    readonly payloadFingerprint: string;
+}): Promise<string>;

package/dist/core/idempotency.js

@@ -0,0 +1,58 @@
+function normalizeForJson(value, seen) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("Idempotency payload numbers must be finite");
+        return value;
+    }
+    if (typeof value === "undefined")
+        return undefined;
+    if (typeof value === "bigint" || typeof value === "symbol" || typeof value === "function") {
+        throw new TypeError("Idempotency payload must be JSON-safe");
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new TypeError("Idempotency payload must not contain cycles");
+        seen.add(value);
+        const result = value.map((entry) => normalizeForJson(entry, seen));
+        seen.delete(value);
+        return result;
+    }
+    if (typeof Blob !== "undefined" && value instanceof Blob) {
+        throw new TypeError("Blob inputs require a caller-provided media fingerprint");
+    }
+    if (typeof value === "object") {
+        if (seen.has(value))
+            throw new TypeError("Idempotency payload must not contain cycles");
+        seen.add(value);
+        const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+        const result = {};
+        for (const [key, entry] of entries) {
+            const normalized = normalizeForJson(entry, seen);
+            if (normalized !== undefined)
+                result[key] = normalized;
+        }
+        seen.delete(value);
+        return result;
+    }
+    throw new TypeError("Unsupported idempotency payload value");
+}
+export function stableSerialize(value) {
+    return JSON.stringify(normalizeForJson(value, new Set()));
+}
+function bytesToHex(bytes) {
+    let result = "";
+    for (const byte of bytes)
+        result += byte.toString(16).padStart(2, "0");
+    return result;
+}
+export async function fingerprint(value) {
+    const bytes = new TextEncoder().encode(stableSerialize(value));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return bytesToHex(new Uint8Array(digest));
+}
+export async function deriveTargetIdempotencyKey(input) {
+    const digest = await fingerprint(input);
+    return `social-${digest}`;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./adapter.js";
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./idempotency.js";
+export * from "./types.js";
+export { iterateItems, type IterationOptions } from "./pagination.js";

package/dist/core/index.js

@@ -0,0 +1,6 @@
+export * from "./adapter.js";
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./idempotency.js";
+export * from "./types.js";
+export { iterateItems } from "./pagination.js";

package/dist/core/pagination.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from "./types.js";
+export interface IterationOptions {
+    readonly maxPages?: number;
+    readonly maxItems?: number;
+    readonly signal?: AbortSignal;
+}
+/** Lazy traversal with explicit bounds, cancellation and repeated-cursor detection. */
+export declare function iterateItems<T>(read: (cursor?: string) => Promise<Page<T>>, options?: IterationOptions): AsyncGenerator<T>;
+/** Cursors bind navigation to its query scope; they are never authorization grants. */
+export declare function encodeCursor(scope: string, value: string): string;
+export declare function decodeCursor(scope: string, cursor: string): string;

package/dist/core/pagination.js

@@ -0,0 +1,81 @@
+import { SocialError } from "./errors.js";
+/** Lazy traversal with explicit bounds, cancellation and repeated-cursor detection. */
+export async function* iterateItems(read, options = {}) {
+    const maxPages = options.maxPages ?? 100;
+    const maxItems = options.maxItems ?? 10_000;
+    if (!Number.isSafeInteger(maxPages) ||
+        maxPages < 1 ||
+        !Number.isSafeInteger(maxItems) ||
+        maxItems < 1)
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "pagination",
+            message: "Iteration bounds must be positive safe integers",
+        });
+    const seen = new Set();
+    let cursor;
+    let count = 0;
+    for (let index = 0; index < maxPages; index++) {
+        if (options.signal?.aborted)
+            throw new SocialError({
+                code: "cancelled",
+                operation: "pagination",
+                message: "Iteration was cancelled",
+            });
+        const page = await read(cursor);
+        for (const item of page.items) {
+            if (options.signal?.aborted)
+                throw new SocialError({
+                    code: "cancelled",
+                    operation: "pagination",
+                    message: "Iteration was cancelled",
+                });
+            yield item;
+            if (++count >= maxItems)
+                return;
+        }
+        if (page.nextCursor === undefined)
+            return;
+        if (!page.nextCursor || seen.has(page.nextCursor))
+            throw new SocialError({
+                code: "upstream_failure",
+                operation: "pagination",
+                message: "Backend returned an empty or repeated pagination cursor",
+            });
+        seen.add(page.nextCursor);
+        cursor = page.nextCursor;
+    }
+}
+/** Cursors bind navigation to its query scope; they are never authorization grants. */
+export function encodeCursor(scope, value) {
+    if (!value || value.length > 16_384)
+        throw new SocialError({
+            code: "upstream_failure",
+            operation: "pagination",
+            message: "Backend returned an invalid cursor",
+        });
+    return `social-v1.${encodeURIComponent(JSON.stringify([scope, value]))}`;
+}
+export function decodeCursor(scope, cursor) {
+    try {
+        if (!cursor.startsWith("social-v1.") || cursor.length > 100_000)
+            throw new Error();
+        const parsed = JSON.parse(decodeURIComponent(cursor.slice(10)));
+        if (!Array.isArray(parsed) ||
+            parsed.length !== 2 ||
+            parsed[0] !== scope ||
+            // oxlint-disable-next-line anti-slop/no-runtime-typeof -- Validate the untrusted decoded cursor tuple.
+            typeof parsed[1] !== "string" ||
+            !parsed[1] ||
+            parsed[1].length > 16_384)
+            throw new Error();
+        return parsed[1];
+    }
+    catch {
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "pagination",
+            message: "Cursor does not belong to this backend, tenant, and query",
+        });
+    }
+}