@opencoredev/social-sdk 0.1.2 → 0.2.1

package/dist/testing/index.js

@@ -0,0 +1,564 @@
+/* oxlint-disable anti-slop/require-readable-spacing -- deterministic mock adapter fixtures stay grouped by surface. */
+import { SocialError, connectedAccountRef, defineAdapter, platformPostRef, } from "../core/index.js";
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+function mockManifest() {
+    return {
+        schemaVersion: 1,
+        backend: "mock",
+        apiRevision: "mock-v1",
+        runtime: ["node", "bun"],
+        capabilities: [
+            { operation: "accounts.read", platform: "*", availability: "available" },
+            { operation: "posts.status", platform: "*", availability: "available" },
+            {
+                operation: "posts.publish",
+                platform: "*",
+                availability: "available",
+                formats: ["text", "image", "video"],
+            },
+            { operation: "comments.read", platform: "*", availability: "available" },
+            { operation: "comments.write", platform: "*", availability: "available" },
+            { operation: "analytics.read", platform: "*", availability: "available" },
+            { operation: "analytics.account.read", platform: "*", availability: "available" },
+            { operation: "analytics.report.read", platform: "*", availability: "available" },
+            { operation: "search.posts", platform: "*", availability: "available" },
+            { operation: "profiles.read", platform: "*", availability: "available" },
+            { operation: "graph.read", platform: "*", availability: "available" },
+            { operation: "graph.follow", platform: "*", availability: "available" },
+            { operation: "graph.unfollow", platform: "*", availability: "available" },
+            { operation: "graph.block", platform: "*", availability: "available" },
+            { operation: "graph.unblock", platform: "*", availability: "available" },
+            { operation: "graph.mute", platform: "*", availability: "available" },
+            { operation: "graph.unmute", platform: "*", availability: "available" },
+            { operation: "posts.read", platform: "*", availability: "available" },
+            { operation: "posts.list", platform: "*", availability: "available" },
+            { operation: "posts.cancelScheduled", platform: "*", availability: "available" },
+            { operation: "posts.deleteBackendRecord", platform: "*", availability: "available" },
+            { operation: "posts.removeFromPlatform", platform: "*", availability: "available" },
+            { operation: "media.upload", platform: "*", availability: "available" },
+            { operation: "messages.read", platform: "*", availability: "available" },
+            { operation: "messages.write", platform: "*", availability: "available" },
+            { operation: "notifications.read", platform: "*", availability: "available" },
+            { operation: "notifications.seen", platform: "*", availability: "available" },
+            { operation: "webhooks.verify", platform: "*", availability: "available" },
+        ],
+    };
+}
+function fixture(name, eventId, occurredAt) {
+    return {
+        name,
+        headers: { "x-mock-signature": name === "invalid" ? "invalid" : "valid" },
+        body: encoder.encode(JSON.stringify({ version: 1, eventId, type: "post.updated", occurredAt })),
+    };
+}
+export function mockBackend(options = {}) {
+    let scenario = options.scenario ?? "immediate-text-success";
+    const backend = options.backendInstance ?? "default";
+    const clock = options.clock ?? (() => new Date("2026-01-01T00:00:00.000Z"));
+    const accountOne = connectedAccountRef({ backend, platform: "x", accountId: "mock-account-1" });
+    const accountTwo = connectedAccountRef({
+        backend,
+        platform: "threads",
+        accountId: "mock-account-2",
+    });
+    const accounts = [
+        { ref: accountOne, displayName: "Mock Creator", handle: "mock.creator", status: "connected" },
+        {
+            ref: accountTwo,
+            displayName: "Mock Studio",
+            handle: "mock.studio",
+            status: scenario === "reconnect-required" ? "reconnect-required" : "connected",
+        },
+    ];
+    let sequence = 0;
+    let deliverySequence = 0;
+    const deliveries = new Map();
+    let processingAdvanced = false;
+    const historyEntries = [];
+    const webhooks = [
+        fixture("valid", "event-1", "2026-01-01T00:00:02.000Z"),
+        fixture("duplicate", "event-1", "2026-01-01T00:00:02.000Z"),
+        fixture("out-of-order", "event-0", "2026-01-01T00:00:01.000Z"),
+        fixture("invalid", "event-invalid", "2026-01-01T00:00:03.000Z"),
+    ];
+    function record(operation, context, account) {
+        historyEntries.push({
+            sequence: ++sequence,
+            operation,
+            backend: context.backendInstance,
+            // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+            ...(account === undefined ? {} : { account }),
+            // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+            ...(context.targetIdempotencyKey === undefined
+                ? {}
+                : { idempotencyKey: context.targetIdempotencyKey }),
+        });
+    }
+    const testing = {
+        setScenario(next) {
+            scenario = next;
+            processingAdvanced = false;
+        },
+        history: () => historyEntries.map((entry) => ({ ...entry })),
+        reset: () => {
+            historyEntries.length = 0;
+            sequence = 0;
+            processingAdvanced = false;
+        },
+        advanceProcessing: () => {
+            processingAdvanced = true;
+        },
+        webhookFixtures: webhooks,
+    };
+    const adapter = defineAdapter({
+        id: "mock",
+        capabilities: mockManifest(),
+        testing,
+        accounts: {
+            async list(_input, context) {
+                record("accounts.list", context);
+                if (scenario === "account-selection-cancellation")
+                    return { items: [] };
+                return { items: accounts };
+            },
+            async get(ref, context) {
+                record("accounts.get", context, ref);
+                const found = accounts.find((account) => account.ref.accountId === ref.accountId);
+                if (found === undefined) {
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "accounts.get",
+                        message: "Mock account was not found",
+                        account: ref,
+                    });
+                }
+                return found;
+            },
+        },
+        posts: {
+            async list(account, _input, context) {
+                record("posts.list", context, account);
+                return { items: [{ id: "mock-post", text: "Mock post" }] };
+            },
+            async get(ref, context) {
+                record("posts.get", context, connectedAccountRef(ref));
+                return { id: ref.postId, text: "Mock post" };
+            },
+            async cancelScheduled(ref, context) {
+                record("posts.cancelScheduled", context, connectedAccountRef(ref));
+                return { state: "cancelled", backendRecord: "retained" };
+            },
+            async deleteBackendRecord(ref, context) {
+                record("posts.deleteBackendRecord", context, connectedAccountRef(ref));
+            },
+            async removeFromPlatform(ref, context) {
+                record("posts.removeFromPlatform", context, connectedAccountRef(ref));
+            },
+            prepareTarget(target) {
+                if (scenario === "unsupported-feature") {
+                    return [
+                        {
+                            code: "mock.unsupported",
+                            message: "This scenario does not support publishing",
+                            severity: "error",
+                            targetIndex: target.targetIndex,
+                        },
+                    ];
+                }
+                if (scenario === "expired-media-url" &&
+                    target.content.media?.some((media) => media.source.kind === "https-url" && media.source.url.includes("expired"))) {
+                    return [
+                        {
+                            code: "media.url_expired",
+                            message: "The mock media URL has expired",
+                            severity: "error",
+                            targetIndex: target.targetIndex,
+                        },
+                    ];
+                }
+                return [];
+            },
+            async publishTarget(target, context) {
+                const deliveryNumber = ++deliverySequence;
+                const execute = async () => {
+                    record("posts.publishTarget", context, target.account);
+                    const base = {
+                        targetIndex: target.targetIndex,
+                        account: target.account,
+                        observedAt: clock().toISOString(),
+                        delivery: {
+                            kind: "delivery",
+                            version: 1,
+                            backend,
+                            platform: target.account.platform,
+                            accountId: target.account.accountId,
+                            deliveryId: `delivery-${deliveryNumber}`,
+                        },
+                    };
+                    if (scenario === "accepted-response-lost") {
+                        throw new SocialError({
+                            code: "ambiguous_outcome",
+                            operation: "posts.publish",
+                            message: "The mock backend accepted the request but the response was lost",
+                            account: target.account,
+                            retryDisposition: { kind: "reconcile-first" },
+                        });
+                    }
+                    if (scenario === "reconnect-required") {
+                        throw new SocialError({
+                            code: "reconnect_required",
+                            operation: "posts.publish",
+                            message: "Reconnect the mock account",
+                            account: target.account,
+                            retryDisposition: { kind: "after-reconnect" },
+                        });
+                    }
+                    if (scenario === "mixed-success-failure" && target.targetIndex % 2 === 1) {
+                        return {
+                            ...base,
+                            state: "failed",
+                            code: "mock.rejected",
+                            message: "Mock target rejected",
+                            retryDisposition: { kind: "never" },
+                        };
+                    }
+                    if (scenario === "expired-permission") {
+                        return {
+                            ...base,
+                            state: "failed",
+                            code: "missing_permission",
+                            message: "Mock permission expired",
+                            retryDisposition: { kind: "after-reconnect" },
+                        };
+                    }
+                    if (scenario === "rate-limited") {
+                        return {
+                            ...base,
+                            state: "failed",
+                            code: "rate_limited",
+                            message: "Mock rate limit",
+                            retryDisposition: { kind: "after-delay", delayMs: 1_000 },
+                        };
+                    }
+                    if (scenario === "provider-state-unknown") {
+                        return {
+                            ...base,
+                            state: "unknown",
+                            reason: "unmapped-state",
+                            backendState: "FUTURE_STATE",
+                            diagnostic: "Unmapped mock provider state",
+                        };
+                    }
+                    if (scenario === "failed-upload-finalization") {
+                        return {
+                            ...base,
+                            state: "failed",
+                            code: "media_error",
+                            message: "Mock upload finalization failed",
+                            retryDisposition: { kind: "never" },
+                        };
+                    }
+                    if (scenario === "media-processing-then-success" && !processingAdvanced) {
+                        return { ...base, state: "processing", backendState: "PROCESSING_MEDIA" };
+                    }
+                    return {
+                        ...base,
+                        state: "published",
+                        post: platformPostRef({
+                            backend,
+                            platform: target.account.platform,
+                            accountId: target.account.accountId,
+                            postId: `post-${deliveryNumber}`,
+                        }),
+                        url: `https://social.example.invalid/${target.account.platform}/post-${deliveryNumber}`,
+                    };
+                };
+                const outcome = await execute();
+                if (outcome.delivery)
+                    deliveries.set(outcome.delivery.deliveryId, structuredClone(outcome));
+                return outcome;
+            },
+            async getDelivery(ref, context) {
+                record("posts.getDelivery", context, connectedAccountRef({
+                    backend: ref.backend,
+                    platform: ref.platform,
+                    accountId: ref.accountId,
+                }));
+                if (scenario === "cancelled-polling" && context.signal?.aborted) {
+                    throw new SocialError({
+                        code: "cancelled",
+                        operation: "posts.getDelivery",
+                        message: "Mock polling was cancelled",
+                    });
+                }
+                const saved = deliveries.get(ref.deliveryId);
+                if (!saved ||
+                    saved.account.accountId !== ref.accountId ||
+                    saved.account.platform !== ref.platform ||
+                    saved.account.backend !== ref.backend)
+                    throw new SocialError({
+                        code: "unauthorized",
+                        operation: "posts.getDelivery",
+                        message: "Mock delivery does not belong to this account.",
+                    });
+                if (saved.state !== "processing" || !processingAdvanced)
+                    return structuredClone(saved);
+                const next = {
+                    ...saved,
+                    state: "published",
+                    observedAt: clock().toISOString(),
+                    post: platformPostRef({
+                        ...saved.account,
+                        postId: ref.deliveryId.replace(/^delivery-/, "post-"),
+                    }),
+                };
+                deliveries.set(ref.deliveryId, next);
+                return structuredClone(next);
+            },
+        },
+        comments: {
+            async list(post, _input, context) {
+                record("comments.list", context, connectedAccountRef(post));
+                if (!accounts.some((account) => account.ref.accountId === post.accountId && account.ref.platform === post.platform))
+                    throw new SocialError({
+                        code: "unauthorized",
+                        operation: "comments.read",
+                        message: "Mock account is not authorized",
+                    });
+                return {
+                    items: [{ id: "comment-1", text: "Can you share more about this?", postId: post.postId }],
+                };
+            },
+            async reply(comment, content, context) {
+                if (comment.commentId !== "comment-1" ||
+                    !content.text.trim() ||
+                    !accounts.some((account) => account.ref.accountId === comment.accountId &&
+                        account.ref.platform === comment.platform))
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "comments.write",
+                        message: "Select the returned mock comment and provide reply text",
+                    });
+                record("comments.reply", context, connectedAccountRef(comment));
+                return { ...comment, commentId: `mock-reply-${sequence}` };
+            },
+        },
+        graph: {
+            async getProfile(account, input, context) {
+                record("profiles.get", context, account);
+                const profile = {
+                    ref: {
+                        kind: "profile",
+                        version: 1,
+                        backend: account.backend,
+                        platform: account.platform,
+                        accountId: account.accountId,
+                        profileId: input.profileId ?? input.handle ?? "mock-profile",
+                    },
+                    displayName: "Mock Profile",
+                };
+                if (input.handle !== undefined)
+                    return { ...profile, handle: input.handle };
+                return profile;
+            },
+            async listRelationships(account, _input, context) {
+                record("graph.listRelationships", context, account);
+                return { items: [] };
+            },
+            async follow(target, context) {
+                record("graph.follow", context, connectedAccountRef(target));
+                return { profile: target, relationship: "following" };
+            },
+            async unfollow(target, context) {
+                record("graph.unfollow", context, connectedAccountRef(target));
+            },
+            async block(target, context) {
+                record("graph.block", context, connectedAccountRef(target));
+                return { profile: target, relationship: "blocked" };
+            },
+            async unblock(target, context) {
+                record("graph.unblock", context, connectedAccountRef(target));
+            },
+            async mute(target, context) {
+                record("graph.mute", context, connectedAccountRef(target));
+                return { profile: target, relationship: "muted" };
+            },
+            async unmute(target, context) {
+                record("graph.unmute", context, connectedAccountRef(target));
+            },
+        },
+        search: {
+            async posts(account, input, context) {
+                record("search.posts", context, account);
+                return {
+                    items: [
+                        {
+                            id: "mock-search-result",
+                            text: input.query,
+                            accountId: account.accountId,
+                        },
+                    ],
+                };
+            },
+        },
+        analytics: {
+            async getAccountMetrics(account, context) {
+                record("analytics.getAccountMetrics", context, account);
+                return [];
+            },
+            async getPostMetrics(post, context) {
+                record("analytics.getPostMetrics", context, connectedAccountRef(post));
+                if (scenario === "no-metric-available")
+                    return [];
+                return [
+                    {
+                        name: "views",
+                        value: 42,
+                        unit: "count",
+                        period: "lifetime",
+                        measuredAt: clock().toISOString(),
+                        source: "mock",
+                    },
+                ];
+            },
+            async getReport(account, query, context) {
+                record("analytics.getReport", context, account);
+                return { query, rows: [], fetchedAt: clock().toISOString(), source: "mock" };
+            },
+        },
+        media: {
+            async upload(_input, account, context) {
+                record("media.upload", context, account);
+                return {
+                    kind: "media",
+                    version: 1,
+                    backend,
+                    mediaId: `media-${sequence}`,
+                    platform: account.platform,
+                    accountId: account.accountId,
+                };
+            },
+        },
+        messages: {
+            async listConversations(account, _input, context) {
+                record("messages.listConversations", context, account);
+                return { items: [{ id: "conversation-1" }] };
+            },
+            async listMessages(ref, _input, context) {
+                record("messages.listMessages", context, connectedAccountRef(ref));
+                return { items: [{ id: "message-1", text: "Hello" }] };
+            },
+            async send(ref, content, context) {
+                record("messages.send", context, connectedAccountRef(ref));
+                return { id: "message-2", text: content.text };
+            },
+        },
+        notifications: {
+            async list(account, _input, context) {
+                record("notifications.list", context, account);
+                return { items: [] };
+            },
+            async markSeen(account, _input, context) {
+                record("notifications.markSeen", context, account);
+            },
+        },
+        webhooks: {
+            async verify(input, context) {
+                record("webhooks.verify", context);
+                return {
+                    valid: input.headers.get("x-mock-signature") === "valid",
+                    method: "mock",
+                    // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+                    ...(input.headers.get("x-mock-signature") === "valid"
+                        ? {}
+                        : { reason: "Invalid mock signature" }),
+                };
+            },
+            async decode(input, context) {
+                record("webhooks.decode", context);
+                const parsed = JSON.parse(decoder.decode(input.body));
+                // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                    throw new SocialError({
+                        code: "invalid_input",
+                        operation: "webhooks.decode",
+                        message: "Invalid mock webhook body",
+                    });
+                }
+                const entries = [];
+                for (const [key, value] of Object.entries(parsed)) {
+                    if (
+                    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                    typeof value === "string" ||
+                        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                        typeof value === "number" ||
+                        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- validated boundary or fixture contract.
+                        typeof value === "boolean" ||
+                        value === null) {
+                        entries.push([key, value]);
+                    }
+                }
+                return Object.fromEntries(entries);
+            },
+        },
+        native: { scenario: () => scenario },
+    });
+    // SAFETY: defineAdapter preserves the supplied testing controller and native mock shape.
+    return adapter;
+}
+export class MemoryIdempotencyStore {
+    #claimsByKey = new Map();
+    #claimsById = new Map();
+    #sequence = 0;
+    async claim(input) {
+        const mapKey = JSON.stringify([input.scope, input.key]);
+        const existing = this.#claimsByKey.get(mapKey);
+        if (existing !== undefined) {
+            if (existing.fingerprint !== input.fingerprint ||
+                JSON.stringify(existing.targetKeys) !== JSON.stringify(input.targetKeys))
+                return { kind: "conflict" };
+            return {
+                kind: "existing",
+                claimId: existing.claimId,
+                outcomes: structuredClone(existing.outcomes),
+            };
+        }
+        const claim = {
+            claimId: `mock-claim-${++this.#sequence}`,
+            fingerprint: input.fingerprint,
+            targetKeys: [...input.targetKeys],
+            outcomes: {},
+        };
+        this.#claimsByKey.set(mapKey, claim);
+        this.#claimsById.set(claim.claimId, claim);
+        return { kind: "new", claimId: claim.claimId, outcomes: {} };
+    }
+    async saveOutcome(input) {
+        const claim = this.#claimsById.get(input.claimId);
+        if (claim === undefined)
+            throw new Error(`Unknown idempotency claim: ${input.claimId}`);
+        if (!claim.targetKeys.includes(input.targetKey)) {
+            throw new Error(`Target does not belong to idempotency claim: ${input.targetKey}`);
+        }
+        claim.outcomes[input.targetKey] = structuredClone(input.outcome);
+    }
+    reset() {
+        this.#claimsByKey.clear();
+        this.#claimsById.clear();
+        this.#sequence = 0;
+    }
+}
+export function mockSharedAccountAuthorization(input) {
+    return {
+        async authorizeTargets({ accounts, context }) {
+            const tenant = context.authorization?.tenantId;
+            return accounts.map((account) => ({
+                account,
+                allowed: tenant !== undefined && (input.memberships[tenant]?.includes(account.accountId) ?? false),
+                // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- validated boundary or fixture contract.
+                ...(tenant === undefined ? { reason: "A tenant is required" } : {}),
+            }));
+        },
+    };
+}

package/dist/testing.d.ts

@@ -0,0 +1 @@
+export * from "./testing/index.js";

package/dist/testing.js

@@ -0,0 +1 @@
+export * from "./testing/index.js";

package/dist/transport/binary.d.ts

@@ -0,0 +1,2 @@
+/** Bounded buffering for APIs that require one small binary image payload. */
+export declare function readBinary(stream: ReadableStream<Uint8Array>, maxBytes: number, signal: AbortSignal): Promise<Uint8Array>;

package/dist/transport/binary.js

@@ -0,0 +1,29 @@
+import { abortable, HttpError } from "./http.js";
+/** Bounded buffering for APIs that require one small binary image payload. */
+export async function readBinary(stream, maxBytes, signal) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const chunk = await abortable(reader.read(), signal);
+            if (chunk.done)
+                break;
+            length += chunk.value.byteLength;
+            if (length > maxBytes)
+                throw new HttpError("Media exceeds its byte limit.", "invalid-input", false);
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        void reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}

package/dist/transport/budget.d.ts

@@ -0,0 +1,3 @@
+import type { AdapterOperationContext } from "../core/types.js";
+/** Sequential requests sharing an operation context consume one elapsed budget. */
+export declare function remainingBudget(context: AdapterOperationContext, now?: number): number;

package/dist/transport/budget.js

@@ -0,0 +1,26 @@
+import { SocialError } from "../core/errors.js";
+const deadlines = new WeakMap();
+/** Sequential requests sharing an operation context consume one elapsed budget. */
+export function remainingBudget(context, now = performance.now()) {
+    const duration = context.retryBudget.maxElapsedMs;
+    if (!Number.isFinite(duration) || duration <= 0)
+        throw new SocialError({
+            code: "invalid_input",
+            operation: "transport",
+            message: "Elapsed request budget must be positive and finite.",
+        });
+    let deadline = deadlines.get(context);
+    if (deadline === undefined) {
+        deadline = now + duration;
+        deadlines.set(context, deadline);
+    }
+    const remaining = deadline - now;
+    if (remaining <= 0)
+        throw new SocialError({
+            code: "timeout",
+            operation: "transport",
+            message: "The operation exhausted its elapsed request budget before the next dispatch.",
+            retryDisposition: { kind: "never" },
+        });
+    return remaining;
+}