@opencoredev/social-sdk 0.1.2 → 0.2.1

package/dist/cloud/lifecycle.js

@@ -0,0 +1,112 @@
+import { SocialError } from "../core/errors.js";
+import { array, object, string } from "../transport/validation.js";
+import { accountMatches } from "./common.js";
+const reject = (message) => {
+    throw new SocialError({ code: "invalid_input", operation: "posts.lifecycle", message });
+};
+const unconfirmed = () => {
+    throw new SocialError({
+        code: "ambiguous_outcome",
+        operation: "posts.lifecycle",
+        message: "The provider did not confirm the mutation. Reconcile before retrying.",
+        retryDisposition: { kind: "reconcile-first" },
+    });
+};
+/** Mutations affect whole provider records. Reject records shared by destinations. */
+export function managedLifecycle(provider, request, now) {
+    const path = (id) => `${provider === "zernio" ? "/v1/posts" : "/v1/social-posts"}/${encodeURIComponent(id)}`;
+    async function owned(ref, id, context) {
+        accountMatches(ref, context);
+        if (!id)
+            reject("A backend record identifier is required.");
+        const response = object(await request(path(id), context));
+        const record = object(response["post"] ?? response);
+        if (record[provider === "zernio" ? "_id" : "id"] !== id)
+            reject("Provider returned a different backend record.");
+        const entries = array(record[provider === "zernio" ? "platforms" : "social_accounts"]).map(object);
+        if (entries.length !== 1)
+            reject("This operation requires a backend record with exactly one destination.");
+        const entry = entries[0];
+        const rawId = provider === "zernio" ? entry["accountId"] : entry["id"];
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- provider payload is validated at this adapter boundary.
+        const accountId = typeof rawId === "string" ? rawId : object(rawId)["_id"];
+        const platform = entry["platform"] === "twitter" ? "x" : entry["platform"];
+        if (accountId !== ref.accountId || platform !== ref.platform)
+            throw new SocialError({
+                code: "unauthorized",
+                operation: "posts.lifecycle",
+                message: "Backend record does not belong to the authorized account and platform.",
+            });
+        return record;
+    }
+    async function deleteRecord(id, context) {
+        const response = object(await request(path(id), context, undefined, {}, "DELETE"));
+        if (provider === "post-for-me"
+            ? response["success"] !== true
+            : response["message"] !== "Post deleted successfully")
+            unconfirmed();
+    }
+    return {
+        async cancelScheduled(ref, context) {
+            const record = await owned(ref, ref.jobId, context);
+            const scheduledAt = record[provider === "zernio" ? "scheduledFor" : "scheduled_at"];
+            if (record["status"] !== "scheduled" ||
+                // oxlint-disable-next-line anti-slop/no-runtime-typeof -- provider payload is validated at this adapter boundary.
+                typeof scheduledAt !== "string" ||
+                !Number.isFinite(Date.parse(scheduledAt)) ||
+                Date.parse(scheduledAt) <= Date.parse(now()))
+                reject("Only a future scheduled record can be cancelled. Reconcile a due or dispatched post.");
+            if (provider === "zernio") {
+                await deleteRecord(ref.jobId, context);
+                return { state: "cancelled", backendRecord: "deleted" };
+            }
+            // A missing/null scheduled_at means publish immediately. Keep the timestamp.
+            // oxlint-disable-next-line anti-slop/no-known-value-widening -- provider payload is validated at this adapter boundary.
+            const body = {
+                caption: string(record["caption"]),
+                social_accounts: [ref.accountId],
+                scheduled_at: string(scheduledAt),
+                isDraft: true,
+            };
+            for (const key of [
+                "media",
+                "platform_configurations",
+                "account_configurations",
+                "external_id",
+            ]) {
+                if (record[key] !== undefined && record[key] !== null)
+                    // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- provider payload is validated at this adapter boundary.
+                    body[key] = record[key];
+            }
+            const result = object(await request(path(ref.jobId), context, body, {}, "PUT"));
+            if (result["id"] !== ref.jobId || result["status"] !== "draft")
+                unconfirmed();
+            return { state: "cancelled", backendRecord: "retained" };
+        },
+        async deleteBackendRecord(ref, context) {
+            const record = await owned(ref, ref.recordId, context);
+            if (record["status"] !== "draft")
+                reject("Delete only a draft backend record. Cancel a future schedule explicitly; never infer native deletion.");
+            await deleteRecord(ref.recordId, context);
+        },
+        // oxlint-disable-next-line anti-slop/no-conditional-empty-object-spread -- provider payload is validated at this adapter boundary.
+        ...(provider === "zernio"
+            ? {
+                async removeFromPlatform(ref, context) {
+                    if (!["x", "threads", "bluesky", "youtube", "linkedin", "facebook"].includes(ref.platform))
+                        reject("Zernio does not support native removal for this platform.");
+                    const id = string(ref.native?.["backendRecordId"]);
+                    const record = await owned(ref, id, context);
+                    const entry = object(array(record["platforms"])[0]);
+                    if (entry["status"] !== "published" || entry["platformPostId"] !== ref.postId)
+                        reject("The backend record does not identify this published native post.");
+                    const result = object(await request(`${path(id)}/unpublish`, context, {
+                        platform: ref.platform === "x" ? "twitter" : ref.platform,
+                    }));
+                    if (result["success"] !== true)
+                        unconfirmed();
+                },
+            }
+            : {}),
+    };
+}

package/dist/cloud/media.d.ts

@@ -0,0 +1,23 @@
+import type { AdapterOperationContext, ConnectedAccountRef, JsonObject, MediaAttachment, MediaRef } from "../core/types.js";
+import { type ManagedOptions } from "./common.js";
+/** Keep this record server-side. A provider storage URL may grant access to the asset. */
+export interface ManagedMediaRecord {
+    readonly ref: MediaRef;
+    readonly publicUrl: string;
+    readonly expiresAt?: string;
+    readonly kind: "image" | "video";
+    readonly mimeType: string;
+}
+export interface ManagedMediaStore {
+    put(record: ManagedMediaRecord): Promise<void>;
+    get(mediaId: string): Promise<ManagedMediaRecord | undefined>;
+}
+export declare class MemoryManagedMediaStore implements ManagedMediaStore {
+    private readonly records;
+    put(record: ManagedMediaRecord): Promise<void>;
+    get(mediaId: string): Promise<ManagedMediaRecord | undefined>;
+}
+export declare function managedMedia(provider: "zernio" | "post-for-me", options: ManagedOptions, presign: (body: JsonObject, context: AdapterOperationContext) => Promise<unknown>): {
+    resolve: (item: MediaAttachment, account: ConnectedAccountRef, context: AdapterOperationContext) => Promise<string>;
+    upload(item: MediaAttachment, account: ConnectedAccountRef, context: AdapterOperationContext): Promise<MediaRef>;
+};

package/dist/cloud/media.js

@@ -0,0 +1,100 @@
+import { SocialError } from "../core/errors.js";
+import { accountMatches, uploadManagedMedia } from "./common.js";
+export class MemoryManagedMediaStore {
+    records = new Map();
+    async put(record) {
+        this.records.set(record.ref.mediaId, structuredClone(record));
+    }
+    async get(mediaId) {
+        const record = this.records.get(mediaId);
+        return record ? structuredClone(record) : undefined;
+    }
+}
+export function managedMedia(provider, options, 
+// oxlint-disable-next-line anti-slop/no-unknown-returns -- provider payload is validated at this adapter boundary.
+presign) {
+    const store = options.mediaStore ?? new MemoryManagedMediaStore();
+    async function resolve(item, account, context) {
+        accountMatches(account, context);
+        if (item.source.kind !== "media-ref")
+            return uploadManagedMedia(item, (body) => presign(body, context), {
+                options,
+                context,
+                provider,
+            });
+        const ref = item.source.ref;
+        if (ref.backend !== account.backend ||
+            ref.accountId !== account.accountId ||
+            ref.platform !== account.platform)
+            throw new SocialError({
+                code: "unauthorized",
+                operation: "media.resolve",
+                message: "Media reference belongs to another account or backend.",
+            });
+        const record = await store.get(ref.mediaId);
+        if (!record ||
+            record.ref.backend !== ref.backend ||
+            record.ref.accountId !== ref.accountId ||
+            record.ref.platform !== ref.platform)
+            throw new SocialError({
+                code: "media_error",
+                operation: "media.resolve",
+                message: "Media reference is unknown to this server-side store.",
+            });
+        if (record.expiresAt &&
+            Date.parse(record.expiresAt) <= (options.clock?.() ?? new Date()).getTime())
+            throw new SocialError({
+                code: "media_error",
+                operation: "media.resolve",
+                message: "Stored media has expired. Upload a new asset explicitly.",
+            });
+        if (record.kind !== item.kind ||
+            (item.mimeType !== undefined && item.mimeType !== record.mimeType))
+            throw new SocialError({
+                code: "media_error",
+                operation: "media.resolve",
+                message: "Media kind or MIME type differs from the stored asset.",
+            });
+        return record.publicUrl;
+    }
+    return {
+        resolve,
+        async upload(item, account, context) {
+            accountMatches(account, context);
+            if (item.source.kind === "media-ref") {
+                await resolve(item, account, context);
+                return item.source.ref;
+            }
+            if (!item.mimeType)
+                throw new SocialError({
+                    code: "invalid_input",
+                    operation: "media.upload",
+                    message: "Provide the asset MIME type.",
+                });
+            const publicUrl = await resolve(item, account, context);
+            const ref = {
+                kind: "media",
+                version: 1,
+                backend: account.backend,
+                platform: account.platform,
+                accountId: account.accountId,
+                mediaId: crypto.randomUUID(),
+            };
+            const uploaded = item.source.kind !== "https-url";
+            const record = {
+                ref,
+                publicUrl,
+                kind: item.kind,
+                mimeType: item.mimeType,
+            };
+            if (provider === "zernio" && uploaded) {
+                const expiresAt = new Date((options.clock?.() ?? new Date()).getTime() + 7 * 86400_000).toISOString();
+                await store.put({ ...record, expiresAt });
+            }
+            else {
+                await store.put(record);
+            }
+            return ref;
+        },
+    };
+}

package/dist/cloud/outcomes.d.ts

@@ -0,0 +1,9 @@
+import type { ConnectedAccountRef, DeliveryOutcome } from "../core/types.js";
+export interface OutcomeContext {
+    account: ConnectedAccountRef;
+    targetIndex: number;
+    observedAt: string;
+}
+/** Never infer destination success from the aggregate HTTP/parent status. */
+export declare function zernioOutcome(value: unknown, context: OutcomeContext): DeliveryOutcome;
+export declare function postForMeOutcome(parentValue: unknown, resultsValue: unknown | undefined, context: OutcomeContext): DeliveryOutcome;

package/dist/cloud/outcomes.js

@@ -0,0 +1,195 @@
+import { array, object, optionalString, string } from "../transport/validation.js";
+function delivery(context, deliveryId) {
+    return {
+        kind: "delivery",
+        version: 1,
+        backend: context.account.backend,
+        platform: context.account.platform,
+        accountId: context.account.accountId,
+        deliveryId,
+    };
+}
+/** Never infer destination success from the aggregate HTTP/parent status. */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- provider payload is validated at this adapter boundary.
+export function zernioOutcome(value, context) {
+    const response = object(value);
+    const post = object(response["post"] ?? response["existingPost"] ?? response);
+    const postId = string(post["_id"]);
+    const platform = context.account.platform === "x" ? "twitter" : context.account.platform;
+    const entries = array(post["platforms"]).map(object);
+    const matches = entries.filter((entry) => {
+        const accountId = 
+        // oxlint-disable-next-line anti-slop/no-runtime-typeof -- provider payload is validated at this adapter boundary.
+        typeof entry["accountId"] === "string"
+            ? entry["accountId"]
+            : // oxlint-disable-next-line anti-slop/no-runtime-typeof -- provider payload is validated at this adapter boundary.
+                entry["accountId"] && typeof entry["accountId"] === "object"
+                    ? optionalString(object(entry["accountId"])["_id"])
+                    : undefined;
+        return entry["platform"] === platform && accountId === context.account.accountId;
+    });
+    const base = { ...context, delivery: delivery(context, postId) };
+    if (matches.length !== 1)
+        return {
+            ...base,
+            state: "unknown",
+            reason: "unmapped-state",
+            diagnostic: "Response has no unique matching account outcome.",
+        };
+    const entry = matches[0];
+    if (!entry)
+        throw new Error("Missing matched outcome");
+    const status = optionalString(entry["status"]) ?? "unknown";
+    const stateBase = { ...base, backendState: status };
+    switch (status) {
+        case "published": {
+            const nativeId = optionalString(entry["platformPostId"]);
+            if (!nativeId)
+                return {
+                    ...stateBase,
+                    state: "unknown",
+                    reason: "unmapped-state",
+                    diagnostic: "Provider reports publication without a native identifier; reconcile to resolve the native post.",
+                };
+            const url = optionalString(entry["platformPostUrl"]);
+            const published = {
+                ...stateBase,
+                state: "published",
+                post: {
+                    kind: "platform-post",
+                    version: 1,
+                    backend: context.account.backend,
+                    platform: context.account.platform,
+                    accountId: context.account.accountId,
+                    postId: nativeId,
+                    native: { backendRecordId: postId },
+                },
+            };
+            return url ? { ...published, url } : published;
+        }
+        case "failed":
+            return {
+                ...stateBase,
+                state: "failed",
+                code: optionalString(entry["errorCategory"]) ?? "upstream_failure",
+                message: "Zernio reports that this destination failed. Inspect account permissions and sanitized provider diagnostics.",
+                retryDisposition: entry["errorCategory"] === "auth_expired"
+                    ? { kind: "after-reconnect" }
+                    : { kind: "never" },
+            };
+        case "processing":
+        case "uploading":
+            return { ...stateBase, state: "processing" };
+        case "pending":
+            return post["status"] === "scheduled"
+                ? {
+                    ...stateBase,
+                    state: "scheduled",
+                    job: {
+                        kind: "scheduled-job",
+                        version: 1,
+                        backend: context.account.backend,
+                        platform: context.account.platform,
+                        accountId: context.account.accountId,
+                        jobId: postId,
+                    },
+                }
+                : { ...stateBase, state: "accepted" };
+        default:
+            return {
+                ...stateBase,
+                state: "unknown",
+                reason: "unmapped-state",
+                diagnostic: "Unmapped destination status; no success or cancellation inferred.",
+            };
+    }
+}
+export function postForMeOutcome(
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- provider payload is validated at this adapter boundary.
+parentValue, 
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- provider payload is validated at this adapter boundary.
+resultsValue, context) {
+    const parent = object(parentValue);
+    const postId = string(parent["id"]);
+    const backendState = optionalString(parent["status"]) ?? "unknown";
+    const base = { ...context, delivery: delivery(context, postId), backendState };
+    if (resultsValue !== undefined) {
+        const results = array(object(resultsValue)["data"]).map(object);
+        const matches = results.filter((result) => result["post_id"] === postId && result["social_account_id"] === context.account.accountId);
+        if (matches.length > 1)
+            return {
+                ...base,
+                state: "unknown",
+                reason: "unmapped-state",
+                diagnostic: "More than one result exists for the target; reconcile the provider records.",
+            };
+        const result = matches[0];
+        if (result) {
+            if (result["success"] === false)
+                return {
+                    ...base,
+                    state: "failed",
+                    code: "upstream_failure",
+                    message: "Post for Me reports that this account's attempt failed.",
+                    retryDisposition: { kind: "never" },
+                };
+            if (result["success"] === true) {
+                const data = object(result["platform_data"]);
+                const postId = optionalString(data["id"]);
+                if (postId) {
+                    const url = optionalString(data["url"]);
+                    const published = {
+                        ...base,
+                        state: "published",
+                        post: {
+                            kind: "platform-post",
+                            version: 1,
+                            backend: context.account.backend,
+                            platform: context.account.platform,
+                            accountId: context.account.accountId,
+                            postId,
+                        },
+                    };
+                    return url ? { ...published, url } : published;
+                }
+            }
+            return {
+                ...base,
+                state: "unknown",
+                reason: "unmapped-state",
+                diagnostic: "Destination result lacks a confirmed native post identifier.",
+            };
+        }
+    }
+    switch (backendState) {
+        case "scheduled":
+            return {
+                ...base,
+                state: "scheduled",
+                job: {
+                    kind: "scheduled-job",
+                    version: 1,
+                    backend: context.account.backend,
+                    platform: context.account.platform,
+                    accountId: context.account.accountId,
+                    jobId: postId,
+                },
+            };
+        case "processing":
+            return { ...base, state: "processing" };
+        case "processed":
+            return {
+                ...base,
+                state: "unknown",
+                reason: "unmapped-state",
+                diagnostic: "The parent is processed, but this account has no confirmed result.",
+            };
+        default:
+            return {
+                ...base,
+                state: "unknown",
+                reason: "unmapped-state",
+                diagnostic: "Unmapped parent status; no destination success inferred.",
+            };
+    }
+}

package/dist/cloud/post-for-me.d.ts

@@ -0,0 +1,69 @@
+export { MemoryManagedMediaStore, type ManagedMediaStore, type ManagedMediaRecord, } from "./media.js";
+import type { AccountRecord, AdapterOperationContext, ConnectedAccountRef, JsonObject, MetricValue, PlatformPostRef } from "../core/types.js";
+import { managedPreparation, type ManagedOptions } from "./common.js";
+export interface PostForMeConnectionOptions {
+    platform: string;
+    externalId: string;
+    permissions: readonly ("posts" | "feeds")[];
+    redirectUrl?: string;
+}
+export declare function postForMe(options: ManagedOptions): {
+    id: string;
+    capabilities: import("../index.js").CapabilityManifest;
+    media: {
+        upload: (item: import("../index.js").MediaAttachment, account: ConnectedAccountRef, context: AdapterOperationContext) => Promise<import("../index.js").MediaRef>;
+    };
+    accounts: {
+        list(input: {
+            cursor?: string;
+            limit?: number;
+        }, context: AdapterOperationContext): Promise<{
+            nextCursor?: string;
+            items: AccountRecord[];
+        }>;
+        get(ref: ConnectedAccountRef, context: AdapterOperationContext): Promise<AccountRecord>;
+    };
+    posts: {
+        list(account: ConnectedAccountRef, input: {
+            readonly cursor?: string;
+            readonly limit?: number;
+        }, context: AdapterOperationContext): Promise<{
+            nextCursor?: string;
+            items: JsonObject[];
+        }>;
+        prepareTarget(target: Parameters<typeof managedPreparation>[0]): import("../index.js").PreparationIssue[];
+        publishTarget(target: Parameters<typeof managedPreparation>[0], context: AdapterOperationContext): Promise<import("../index.js").DeliveryOutcome>;
+        getDelivery(ref: {
+            deliveryId: string;
+            accountId: string;
+            platform: string;
+            backend: string;
+        }, context: AdapterOperationContext): Promise<import("../index.js").DeliveryOutcome>;
+        get(ref: PlatformPostRef, context: AdapterOperationContext): Promise<JsonObject>;
+        removeFromPlatform?: (ref: PlatformPostRef, context: AdapterOperationContext) => Promise<void>;
+        cancelScheduled(ref: import("../index.js").ScheduledJobRef, context: AdapterOperationContext): Promise<import("../index.js").ScheduleCancellation>;
+        deleteBackendRecord(ref: import("../index.js").BackendPostRef, context: AdapterOperationContext): Promise<void>;
+    };
+    analytics: {
+        getPostMetrics(ref: PlatformPostRef, context: AdapterOperationContext): Promise<readonly MetricValue[]>;
+    };
+    webhooks: {
+        verify(input: {
+            headers: Headers;
+            body: Uint8Array;
+        }): Promise<{
+            valid: true;
+            method: "shared-secret";
+        }>;
+        decode(input: {
+            headers: Headers;
+            body: Uint8Array;
+        }, context: AdapterOperationContext): Promise<JsonObject>;
+    };
+    native: {
+        createConnection(input: PostForMeConnectionOptions, context: AdapterOperationContext): Promise<{
+            url: string;
+            platform: string;
+        }>;
+    };
+};