@opencoredev/social-sdk 0.4.0 → 0.5.0

package/dist/cli.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import type { SocialAdapter } from "./core/index.js";
 /** Adapters the diagnostic CLI can construct offline. */
-export declare const adapterNames: readonly ["mock", "zernio", "post-for-me", "bluesky", "x", "threads", "youtube", "tiktok", "instagram", "linkedin"];
+export declare const adapterNames: readonly ["mock", "zernio", "post-for-me", "postfast", "bluesky", "x", "threads", "youtube", "tiktok", "instagram", "linkedin"];
 export type AdapterName = (typeof adapterNames)[number];
 export declare function isAdapterName(value: string): value is AdapterName;
 export declare function createDiagnosticAdapter(name: AdapterName, accountId?: string): SocialAdapter<unknown>;

package/dist/cli.js

@@ -7,6 +7,7 @@ import { decodePublishRequest, PublishRequestInputError } from "./cli-request.js
 import { mockBackend } from "./testing/index.js";
 import { zernio } from "./cloud/zernio.js";
 import { postForMe } from "./cloud/post-for-me.js";
+import { postfast } from "./cloud/postfast.js";
 import { bluesky } from "./platforms/bluesky.js";
 import { x } from "./platforms/x.js";
 import { threads } from "./platforms/threads.js";
@@ -19,6 +20,7 @@ export const adapterNames = [
     "mock",
     "zernio",
     "post-for-me",
+    "postfast",
     "bluesky",
     "x",
     "threads",
@@ -37,6 +39,7 @@ const environmentNames = {
     mock: [],
     zernio: ["ZERNIO_API_KEY"],
     "post-for-me": ["POST_FOR_ME_API_KEY"],
+    postfast: ["POSTFAST_API_KEY"],
     bluesky: ["BLUESKY_SERVICE", "BLUESKY_DID", "BLUESKY_ACCESS_JWT"],
     x: ["X_USER_ID", "X_ACCESS_TOKEN"],
     threads: ["THREADS_USER_ID", "THREADS_ACCESS_TOKEN"],
@@ -56,6 +59,8 @@ export function createDiagnosticAdapter(name, accountId = "diagnostic-account")
             return zernio({ apiKey: "offline-placeholder", fetch: noNetwork });
         case "post-for-me":
             return postForMe({ apiKey: "offline-placeholder", fetch: noNetwork });
+        case "postfast":
+            return postfast({ apiKey: "offline-placeholder", fetch: noNetwork });
         case "bluesky":
             return bluesky({
                 auth: { service: "https://bsky.social", did: accountId, accessJwt: "offline-placeholder" },

package/dist/cloud/common.d.ts

@@ -1,5 +1,5 @@
 import type { ManagedMediaStore } from "./media.js";
-import type { AdapterOperationContext, CapabilityManifest, ConnectedAccountRef, JsonObject, JsonValue, MediaAttachment, Platform, PreparationIssue, PreparedPublishTarget } from "../core/types.js";
+import type { AdapterOperationContext, CapabilityDeclaration, CapabilityManifest, ConnectedAccountRef, JsonObject, JsonValue, MediaAttachment, Platform, PreparationIssue, PreparedPublishTarget } from "../core/types.js";
 import { type HttpOptions } from "../transport/http.js";
 import { type JsonField } from "../transport/validation.js";
 export interface ManagedOptions extends HttpOptions {
@@ -11,11 +11,15 @@ export interface ManagedOptions extends HttpOptions {
 }
 export declare const selectedPlatforms: readonly ["x", "threads", "bluesky", "youtube", "tiktok", "instagram", "linkedin", "facebook"];
 export declare function platform(value: JsonField): Platform;
-export declare function managedHttp(origin: string, options: ManagedOptions): (path: string, context: AdapterOperationContext, body?: JsonObject, query?: Record<string, string>, method?: "GET" | "POST" | "PUT" | "DELETE") => Promise<JsonValue>;
-export declare function capabilityManifest(backend: string, apiRevision: string, operations: readonly string[]): CapabilityManifest;
+/** How a provider expects its server-side API key. Defaults to a bearer token. */
+export type ManagedAuthHeader = (apiKey: string) => readonly [name: string, value: string];
+export declare function managedHttp(origin: string, options: ManagedOptions, authHeader?: ManagedAuthHeader): (path: string, context: AdapterOperationContext, body?: JsonObject, query?: Record<string, string>, method?: "GET" | "POST" | "PUT" | "DELETE") => Promise<JsonValue>;
+export type PublishFormats = (platform: (typeof selectedPlatforms)[number]) => CapabilityDeclaration["formats"];
+export declare const publishFormats: PublishFormats;
+export declare function capabilityManifest(backend: string, apiRevision: string, operations: readonly string[], formats?: PublishFormats): CapabilityManifest;
 export declare function optionsObject(target: PreparedPublishTarget): JsonObject;
 /** Every accepted normalized option has an intentional provider mapping. */
-export declare function managedOptionIssues(target: PreparedPublishTarget, provider: "zernio" | "post-for-me"): PreparationIssue[];
+export declare function managedOptionIssues(target: PreparedPublishTarget, provider: "zernio" | "post-for-me" | "postfast"): PreparationIssue[];
 export declare function managedPreparation(target: PreparedPublishTarget): PreparationIssue[];
 export declare function uploadManagedMedia(item: MediaAttachment, presign: (body: JsonObject) => Promise<JsonValue>, config: {
     options: ManagedOptions;

package/dist/cloud/common.js

@@ -25,7 +25,8 @@ export function platform(value) {
         });
     return slug;
 }
-export function managedHttp(origin, options) {
+const bearer = (apiKey) => ["Authorization", `Bearer ${apiKey}`];
+export function managedHttp(origin, options, authHeader = bearer) {
     if (!options.apiKey.trim())
         throw new SocialError({
             code: "invalid_config",
@@ -37,10 +38,8 @@ export function managedHttp(origin, options) {
         const url = new URL(origin + path);
         for (const [key, value] of Object.entries(query))
             url.searchParams.set(key, value);
-        const headers = new Headers({
-            Authorization: `Bearer ${options.apiKey}`,
-            "Content-Type": "application/json",
-        });
+        const headers = new Headers({ "Content-Type": "application/json" });
+        headers.set(...authHeader(options.apiKey));
         if (context.targetIdempotencyKey && origin.includes("zernio.com"))
             headers.set(path === "/v1/posts" ? "x-request-id" : "Idempotency-Key", context.targetIdempotencyKey);
         try {
@@ -100,14 +99,14 @@ export function managedHttp(origin, options) {
         }
     };
 }
-function publishFormats(platform) {
+export const publishFormats = (platform) => {
     if (platform === "youtube")
         return ["video"];
     if (platform === "instagram" || platform === "tiktok")
         return ["image", "video", "carousel"];
     return ["text", "image", "video", "carousel"];
-}
-export function capabilityManifest(backend, apiRevision, operations) {
+};
+export function capabilityManifest(backend, apiRevision, operations, formats = publishFormats) {
     return {
         schemaVersion: 1,
         backend,
@@ -118,7 +117,7 @@ export function capabilityManifest(backend, apiRevision, operations) {
             operation,
             availability: "available",
             ...definedFields({
-                formats: operation === "posts.publish" ? publishFormats(platform) : undefined,
+                formats: operation === "posts.publish" ? formats(platform) : undefined,
             }),
             notes: "Contract implementation; live account verification and provider/platform eligibility are separate.",
         }))),

package/dist/cloud/media.d.ts

@@ -4,6 +4,8 @@ import { type ManagedOptions } from "./common.js";
 export interface ManagedMediaRecord {
     readonly ref: MediaRef;
     readonly publicUrl: string;
+    /** Storage key for providers that reference uploads by key rather than URL, such as PostFast. */
+    readonly providerKey?: string;
     readonly expiresAt?: string;
     readonly kind: "image" | "video";
     readonly mimeType: string;
@@ -17,6 +19,8 @@ export declare class MemoryManagedMediaStore implements ManagedMediaStore {
     put(record: ManagedMediaRecord): Promise<void>;
     get(mediaId: string): Promise<ManagedMediaRecord | undefined>;
 }
+/** Look up an uploaded asset and prove it belongs to this account and matches the attachment. */
+export declare function storedMedia(item: MediaAttachment, ref: MediaRef, account: ConnectedAccountRef, store: ManagedMediaStore, options: Pick<ManagedOptions, "clock">): Promise<ManagedMediaRecord>;
 export declare function managedMedia(provider: "zernio" | "post-for-me", options: ManagedOptions, presign: (body: JsonObject, context: AdapterOperationContext) => Promise<JsonValue>): {
     resolve: (item: MediaAttachment, account: ConnectedAccountRef, context: AdapterOperationContext) => Promise<string>;
     upload(item: MediaAttachment, account: ConnectedAccountRef, context: AdapterOperationContext): Promise<MediaRef>;

package/dist/cloud/media.js

@@ -10,6 +10,42 @@ export class MemoryManagedMediaStore {
         return record ? structuredClone(record) : undefined;
     }
 }
+/** Look up an uploaded asset and prove it belongs to this account and matches the attachment. */
+export async function storedMedia(item, ref, account, store, options) {
+    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;
+}
 export function managedMedia(provider, options, presign) {
     const store = options.mediaStore ?? new MemoryManagedMediaStore();
     async function resolve(item, account, context) {
@@ -26,40 +62,7 @@ export function managedMedia(provider, options, presign) {
                 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 (await storedMedia(item, item.source.ref, account, store, options)).publicUrl;
     }
     return {
         resolve,

package/dist/cloud/postfast.d.ts

@@ -0,0 +1,54 @@
+export { MemoryManagedMediaStore, type ManagedMediaStore, type ManagedMediaRecord, } from "./media.js";
+import type { AccountRecord, AdapterOperationContext, BackendPostRef, ConnectedAccountRef, DeliveryOutcome, MediaAttachment, MediaRef, MetricValue, PlatformPostRef, PreparationIssue, ScheduleCancellation, ScheduledJobRef } from "../core/types.js";
+import { managedPreparation, type ManagedOptions } from "./common.js";
+export interface PostFastConnectLinkOptions {
+    /** PostFast platform values such as `X` or `INSTAGRAM`. Omit to offer every platform. */
+    platforms?: readonly string[];
+    /** Days until the link expires. PostFast defaults to 7. */
+    expiryDays?: number;
+    redirectUrl?: string;
+    /** Your own identifier for the person connecting accounts. */
+    externalId?: string;
+}
+/**
+ * PostFast managed backend. PostFast only schedules posts, so every target needs a
+ * future `schedule.at`. Media is uploaded to PostFast storage and referenced by key.
+ */
+export declare function postfast(options: ManagedOptions): {
+    id: string;
+    capabilities: import("../index.js").CapabilityManifest;
+    media: {
+        upload(item: MediaAttachment, target: ConnectedAccountRef, context: AdapterOperationContext): Promise<MediaRef>;
+    };
+    accounts: {
+        list(input: {
+            cursor?: string;
+            limit?: number;
+        }, context: AdapterOperationContext): Promise<{
+            nextCursor?: string;
+            items: AccountRecord[];
+        }>;
+        get(ref: ConnectedAccountRef, context: AdapterOperationContext): Promise<AccountRecord>;
+    };
+    posts: {
+        prepareTarget(target: Parameters<typeof managedPreparation>[0]): PreparationIssue[];
+        publishTarget(target: Parameters<typeof managedPreparation>[0], context: AdapterOperationContext): Promise<DeliveryOutcome>;
+        getDelivery(ref: {
+            deliveryId: string;
+            accountId: string;
+            platform: string;
+            backend: string;
+        }, context: AdapterOperationContext): Promise<DeliveryOutcome>;
+        cancelScheduled(ref: ScheduledJobRef, context: AdapterOperationContext): Promise<ScheduleCancellation>;
+        deleteBackendRecord(ref: BackendPostRef, context: AdapterOperationContext): Promise<void>;
+    };
+    analytics: {
+        getPostMetrics(ref: PlatformPostRef, context: AdapterOperationContext): Promise<readonly MetricValue[]>;
+    };
+    native: {
+        /** Create a hosted link where someone connects their social accounts to your workspace. */
+        createConnectLink(input: PostFastConnectLinkOptions, context: AdapterOperationContext): Promise<{
+            url: string;
+        }>;
+    };
+};

package/dist/cloud/postfast.js

@@ -0,0 +1,578 @@
+import { MemoryManagedMediaStore, storedMedia } from "./media.js";
+export { MemoryManagedMediaStore, } from "./media.js";
+import { defineAdapter } from "../core/adapter.js";
+import { SocialError } from "../core/errors.js";
+import { definedFields } from "../core/fields.js";
+import { remainingBudget } from "../transport/budget.js";
+import { httpsUrl, upload } from "../transport/upload.js";
+import { array, isBoolean, isString, object, optionalNumber, optionalString, string, } from "../transport/validation.js";
+import { accountMatches, capabilityManifest, managedHttp, managedOptionIssues, managedPreparation, optionsObject, publishFormats, selectedPlatforms, } from "./common.js";
+const nativePlatforms = new Map([
+    ["X", "x"],
+    ["THREADS", "threads"],
+    ["BLUESKY", "bluesky"],
+    ["YOUTUBE", "youtube"],
+    ["TIKTOK", "tiktok"],
+    ["INSTAGRAM", "instagram"],
+    ["LINKEDIN", "linkedin"],
+    ["FACEBOOK", "facebook"],
+]);
+const mimeTypes = [
+    "image/jpeg",
+    "image/png",
+    "image/gif",
+    "image/webp",
+    "video/mp4",
+    "video/webm",
+    "video/mov",
+    "video/quicktime",
+];
+// PostFast's Bluesky guide documents text and image posts only.
+const postfastFormats = (platform) => platform === "bluesky" ? ["text", "image", "carousel"] : publishFormats(platform);
+const maxBytes = { image: 10 * 1024 * 1024, video: 250 * 1024 * 1024 };
+const tiktokPrivacy = new Map([
+    ["PUBLIC_TO_EVERYONE", "PUBLIC"],
+    ["MUTUAL_FOLLOW_FRIENDS", "MUTUAL_FRIENDS"],
+    ["FOLLOWER_OF_CREATOR", "FOLLOWER_OF_CREATOR"],
+    ["SELF_ONLY", "ONLY_ME"],
+]);
+const reject = (operation, message) => {
+    throw new SocialError({ code: "invalid_input", operation, message });
+};
+/** PostFast returns counters as bigint strings. Keep only values a JS number holds exactly. */
+function count(value) {
+    const parsed = isString(value) && /^\d+$/.test(value) ? Number(value) : optionalNumber(value);
+    return parsed !== undefined && Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+/**
+ * PostFast managed backend. PostFast only schedules posts, so every target needs a
+ * future `schedule.at`. Media is uploaded to PostFast storage and referenced by key.
+ */
+export function postfast(options) {
+    const request = managedHttp("https://api.postfa.st", options, (apiKey) => ["pf-api-key", apiKey]);
+    const store = options.mediaStore ?? new MemoryManagedMediaStore();
+    const clock = () => options.clock?.() ?? new Date();
+    const now = () => clock().toISOString();
+    const allowHost = options.uploadHostAllowed ??
+        ((host) => host === "s3.amazonaws.com" ||
+            (host.startsWith("postfast-uploads.s3.") && host.endsWith(".amazonaws.com")));
+    const account = (value, backend) => {
+        const row = object(value);
+        const slug = nativePlatforms.get(string(row["platform"]));
+        if (!slug)
+            return undefined;
+        const handle = optionalString(row["platformUsername"]);
+        return {
+            ref: {
+                kind: "connected-account",
+                version: 1,
+                backend,
+                platform: slug,
+                accountId: string(row["id"]),
+            },
+            displayName: optionalString(row["displayName"]) || handle || string(row["id"]),
+            ...definedFields({ handle: handle || undefined }),
+            status: row["connectionStatus"] === "CONNECTED"
+                ? "connected"
+                : row["connectionStatus"] === "DISABLED"
+                    ? "reconnect-required"
+                    : "unknown",
+        };
+    };
+    const accounts = async (context) => array(await request("/social-media/my-social-accounts", context)).flatMap((value) => {
+        const parsed = account(value, context.backendInstance);
+        return parsed ? [parsed] : [];
+    });
+    /** Read one post record and prove it belongs to the referenced account. */
+    const record = async (id, ref, context, operation) => {
+        accountMatches(ref, context);
+        if (!id)
+            reject(operation, "A PostFast post identifier is required.");
+        const result = object(await request("/social-posts", context, undefined, { ids: id, limit: "1" }));
+        const row = array(result["data"])
+            .map(object)
+            .find((item) => item["id"] === id);
+        if (!row)
+            throw new SocialError({
+                code: "not_found",
+                operation,
+                message: "PostFast has no post with this identifier in the workspace.",
+            });
+        if (row["socialMediaId"] !== ref.accountId)
+            throw new SocialError({
+                code: "unauthorized",
+                operation,
+                message: "The PostFast post does not belong to the authorized account.",
+            });
+        return row;
+    };
+    const outcome = (row, target, targetIndex) => {
+        const id = string(row["id"]);
+        const status = optionalString(row["status"]) ?? "unknown";
+        const delivery = {
+            kind: "delivery",
+            version: 1,
+            backend: target.backend,
+            platform: target.platform,
+            accountId: target.accountId,
+            deliveryId: id,
+        };
+        const base = {
+            targetIndex,
+            account: target,
+            delivery,
+            backendState: status,
+            observedAt: now(),
+        };
+        switch (status) {
+            case "SCHEDULED":
+                if (row["approvalStatus"] === "PENDING_APPROVAL")
+                    return { ...base, backendState: "SCHEDULED/PENDING_APPROVAL", state: "accepted" };
+                return {
+                    ...base,
+                    state: "scheduled",
+                    job: {
+                        kind: "scheduled-job",
+                        version: 1,
+                        backend: target.backend,
+                        platform: target.platform,
+                        accountId: target.accountId,
+                        jobId: id,
+                    },
+                };
+            case "PUBLISHED": {
+                const postId = optionalString(row["platformPostId"]);
+                if (!postId)
+                    return {
+                        ...base,
+                        state: "unknown",
+                        reason: "unmapped-state",
+                        diagnostic: "PostFast reports publication without a native post identifier.",
+                    };
+                return {
+                    ...base,
+                    state: "published",
+                    post: {
+                        kind: "platform-post",
+                        version: 1,
+                        backend: target.backend,
+                        platform: target.platform,
+                        accountId: target.accountId,
+                        postId,
+                        native: { backendRecordId: id },
+                    },
+                };
+            }
+            case "FAILED":
+                return {
+                    ...base,
+                    state: "failed",
+                    code: "upstream_failure",
+                    message: "PostFast reports that this post failed. Inspect the account connection and the post in PostFast.",
+                    retryDisposition: { kind: "never" },
+                };
+            default:
+                return {
+                    ...base,
+                    state: "unknown",
+                    reason: "unmapped-state",
+                    diagnostic: "PostFast returned a post status this adapter does not map.",
+                };
+        }
+    };
+    /** Upload bytes to PostFast storage and return the storage key. */
+    const uploadBytes = async (item, context) => {
+        if (item.kind === "document")
+            throw new SocialError({
+                code: "unsupported_capability",
+                operation: "media.upload",
+                message: "PostFast accepts image and video media only through this adapter.",
+            });
+        const source = item.source;
+        if (source.kind === "https-url" || source.kind === "media-ref")
+            return reject("media.upload", "Only uploadable bytes can be sent to PostFast storage.");
+        const mimeType = string(item.mimeType);
+        if (!mimeTypes.some((value) => value === mimeType))
+            reject("media.upload", "PostFast does not accept this media type.");
+        const size = item.byteSize ?? (source.kind === "blob" ? source.blob.size : undefined);
+        if (size !== undefined && size > maxBytes[item.kind])
+            throw new SocialError({
+                code: "media_error",
+                operation: "media.upload",
+                message: "PostFast accepts images up to 10 MB and videos up to 250 MB.",
+            });
+        const signed = array(await request("/file/get-signed-upload-urls", context, { contentType: mimeType, count: 1 }));
+        if (signed.length !== 1)
+            throw new SocialError({
+                code: "upstream_failure",
+                operation: "media.upload",
+                message: "PostFast returned an unexpected number of upload URLs.",
+            });
+        const entry = object(signed[0]);
+        const key = string(entry["key"]);
+        await upload({
+            url: string(entry["signedUrl"]),
+            source: {
+                mimeType,
+                ...definedFields({ size, body: source.kind === "blob" ? source.blob : undefined }),
+                open: source.kind === "blob" ? () => source.blob.stream() : source.open,
+            },
+            allowHost,
+            maxBytes: maxBytes[item.kind],
+            timeoutMs: remainingBudget(context),
+            ...definedFields({ fetch: options.fetch, signal: context.signal }),
+        });
+        return key;
+    };
+    const mediaKey = async (item, target, context) => {
+        if (item.source.kind !== "media-ref")
+            return uploadBytes(item, context);
+        const stored = await storedMedia(item, item.source.ref, target, store, options);
+        if (!stored.providerKey)
+            throw new SocialError({
+                code: "media_error",
+                operation: "media.resolve",
+                message: "This media reference was not uploaded to PostFast storage.",
+            });
+        return stored.providerKey;
+    };
+    const adapter = defineAdapter({
+        id: "postfast",
+        capabilities: capabilityManifest("postfast", "REST API, docs fetched 2026-09-24", [
+            "accounts.read",
+            "posts.publish",
+            "posts.status",
+            "posts.cancelScheduled",
+            "posts.deleteBackendRecord",
+            "analytics.read",
+            "media.upload",
+        ], postfastFormats),
+        media: {
+            async upload(item, target, context) {
+                accountMatches(target, context);
+                if (item.kind === "document")
+                    throw new SocialError({
+                        code: "unsupported_capability",
+                        operation: "media.upload",
+                        message: "PostFast accepts image and video media only through this adapter.",
+                    });
+                if (item.source.kind === "media-ref") {
+                    await mediaKey(item, target, context);
+                    return item.source.ref;
+                }
+                if (!item.mimeType)
+                    reject("media.upload", "Provide the asset MIME type.");
+                const key = await uploadBytes(item, context);
+                const ref = {
+                    kind: "media",
+                    version: 1,
+                    backend: target.backend,
+                    platform: target.platform,
+                    accountId: target.accountId,
+                    mediaId: crypto.randomUUID(),
+                };
+                // PostFast references uploads by key. The URL without its signature is kept for
+                // inspection only and never grants access.
+                const stored = {
+                    ref,
+                    publicUrl: `https://s3.amazonaws.com/postfast-uploads/${key}`,
+                    providerKey: key,
+                    kind: item.kind,
+                    mimeType: string(item.mimeType),
+                };
+                await store.put(stored);
+                return ref;
+            },
+        },
+        accounts: {
+            async list(input, context) {
+                const offset = input.cursor === undefined ? 0 : Number(input.cursor);
+                const limit = input.limit ?? 25;
+                if (!Number.isSafeInteger(offset) ||
+                    offset < 0 ||
+                    !Number.isSafeInteger(limit) ||
+                    limit < 1 ||
+                    limit > 100)
+                    reject("accounts.read", "Use an opaque returned cursor and a page size from 1 to 100.");
+                // PostFast returns every account in one response; page locally.
+                const all = await accounts(context);
+                const next = offset + limit < all.length ? String(offset + limit) : undefined;
+                return {
+                    items: all.slice(offset, offset + limit),
+                    ...definedFields({ nextCursor: next }),
+                };
+            },
+            async get(ref, context) {
+                accountMatches(ref, context);
+                const found = (await accounts(context)).find((item) => item.ref.accountId === ref.accountId && item.ref.platform === ref.platform);
+                if (!found)
+                    throw new SocialError({
+                        code: "not_found",
+                        operation: "accounts.read",
+                        message: "PostFast has no connected account matching this reference.",
+                    });
+                return found;
+            },
+        },
+        posts: {
+            prepareTarget(target) {
+                const issues = [
+                    ...managedPreparation(target),
+                    ...managedOptionIssues(target, "postfast"),
+                ];
+                const fail = (code, message, severity = "error") => issues.push({ code, message, severity, targetIndex: target.targetIndex });
+                const at = target.schedule?.at;
+                if (!at)
+                    fail("schedule.required", "PostFast only schedules posts. Set a future schedule time for this target.");
+                else if (!(Date.parse(at) > clock().getTime()))
+                    fail("schedule.past", "PostFast requires a schedule time in the future.");
+                const media = target.content.media ?? [];
+                for (const item of media) {
+                    if (item.kind === "document") {
+                        fail("media.document_unsupported", "PostFast accepts image and video media only.");
+                        continue;
+                    }
+                    if (item.source.kind === "https-url")
+                        fail("media.url_unsupported", "PostFast accepts uploaded files only. Pass the bytes or a PostFast media reference.");
+                    if (item.mimeType && !mimeTypes.some((value) => value === item.mimeType))
+                        fail("media.mime_unsupported", "PostFast does not accept this media type.");
+                    const size = item.byteSize ?? (item.source.kind === "blob" ? item.source.blob.size : undefined);
+                    if (size !== undefined && size > maxBytes[item.kind])
+                        fail("media.too_large", "PostFast accepts images up to 10 MB and videos up to 250 MB.");
+                    if (item.altText !== undefined)
+                        fail("media.alt_text_unsupported", "PostFast's post schema does not document alt text. Choose a backend with an explicit accessibility mapping.");
+                }
+                if (target.account.platform === "bluesky" && media.some((item) => item.kind === "video"))
+                    fail("bluesky.video_unsupported", "PostFast publishes text and images to Bluesky.");
+                const config = optionsObject(target);
+                if (target.account.platform === "x" &&
+                    config["replySettings"] !== undefined &&
+                    config["replySettings"] !== "everyone")
+                    fail("x.reply_settings_unsupported", "PostFast does not document X reply settings.");
+                if (target.account.platform === "tiktok" &&
+                    config["draft"] !== true &&
+                    media.some((item) => item.kind === "video")) {
+                    if (config["privacy"] !== "PUBLIC_TO_EVERYONE")
+                        fail("tiktok.privacy_unsupported", "PostFast publishes TikTok videos with the account's default privacy. Save a TikTok draft to keep a video private.");
+                    else
+                        fail("tiktok.privacy_account_default", "PostFast publishes TikTok videos with the account's default privacy.", "warning");
+                }
+                return issues;
+            },
+            async publishTarget(target, context) {
+                accountMatches(target.account, context);
+                const at = target.schedule?.at;
+                if (!at || !(Date.parse(at) > clock().getTime()))
+                    reject("posts.publish", "PostFast requires a future schedule time.");
+                const mediaItems = [];
+                for (const [index, item] of (target.content.media ?? []).entries())
+                    mediaItems.push({
+                        key: await mediaKey(item, target.account, context),
+                        type: item.kind === "video" ? "VIDEO" : "IMAGE",
+                        sortOrder: index,
+                    });
+                const config = optionsObject(target);
+                const controls = {};
+                if (target.account.platform === "youtube") {
+                    controls["youtubeTitle"] = string(config["title"]);
+                    controls["youtubePrivacy"] = string(config["visibility"]).toUpperCase();
+                    const madeForKids = config["madeForKids"];
+                    if (isBoolean(madeForKids))
+                        controls["youtubeMadeForKids"] = madeForKids;
+                }
+                if (target.account.platform === "instagram" && isBoolean(config["shareToFeed"]))
+                    controls["instagramPostToGrid"] = config["shareToFeed"];
+                if (target.account.platform === "tiktok") {
+                    const privacy = tiktokPrivacy.get(String(config["privacy"]));
+                    if (privacy)
+                        controls["tiktokPrivacy"] = privacy;
+                    // prepareTarget requires every one of these choices to be a boolean.
+                    for (const [nativeKey, optionKey, negate] of [
+                        ["tiktokAllowComments", "disableComments", true],
+                        ["tiktokAllowDuet", "disableDuet", true],
+                        ["tiktokAllowStitch", "disableStitch", true],
+                        ["tiktokBrandOrganic", "ownBrand", false],
+                        ["tiktokBrandContent", "brandedContent", false],
+                        ["tiktokIsAigc", "aiGenerated", false],
+                        ["tiktokIsDraft", "draft", false],
+                    ]) {
+                        const value = config[optionKey];
+                        if (isBoolean(value))
+                            controls[nativeKey] = negate ? !value : value;
+                    }
+                }
+                // Media uploads can outlast a near schedule, and PostFast rejects a past time.
+                if (!(Date.parse(string(at)) > clock().getTime()))
+                    reject("posts.publish", "The schedule time passed while media uploaded.");
+                const response = object(await request("/social-posts", context, {
+                    posts: [
+                        {
+                            content: target.content.text ?? "",
+                            socialMediaId: target.account.accountId,
+                            scheduledAt: new Date(string(at)).toISOString(),
+                            ...definedFields({ mediaItems: mediaItems.length ? mediaItems : undefined }),
+                        },
+                    ],
+                    status: "SCHEDULED",
+                    ...definedFields({
+                        controls: Object.keys(controls).length ? controls : undefined,
+                    }),
+                }));
+                const ids = array(response["postIds"]);
+                const id = ids.length === 1 && isString(ids[0]) ? ids[0] : undefined;
+                if (!id)
+                    return {
+                        state: "unknown",
+                        reason: "ambiguous-submission",
+                        diagnostic: "PostFast did not return exactly one post identifier.",
+                        targetIndex: target.targetIndex,
+                        account: target.account,
+                        observedAt: now(),
+                    };
+                try {
+                    return outcome(await record(id, target.account, context, "posts.publish"), target.account, target.targetIndex);
+                }
+                catch (error) {
+                    // A post was written, so an ownership mismatch stays an uncertain write instead of an error.
+                    if (error instanceof SocialError && error.code === "unauthorized")
+                        return {
+                            state: "unknown",
+                            reason: "ambiguous-submission",
+                            diagnostic: "PostFast returned a post that does not belong to the requested account.",
+                            targetIndex: target.targetIndex,
+                            account: target.account,
+                            observedAt: now(),
+                        };
+                    // Keep the created post visible even if the follow-up read fails.
+                    return {
+                        state: "accepted",
+                        targetIndex: target.targetIndex,
+                        account: target.account,
+                        delivery: {
+                            kind: "delivery",
+                            version: 1,
+                            backend: target.account.backend,
+                            platform: target.account.platform,
+                            accountId: target.account.accountId,
+                            deliveryId: id,
+                        },
+                        observedAt: now(),
+                    };
+                }
+            },
+            async getDelivery(ref, context) {
+                const slug = selectedPlatforms.find((value) => value === ref.platform);
+                if (!slug)
+                    return reject("posts.status", "This platform is outside PostFast coverage.");
+                const target = {
+                    kind: "connected-account",
+                    version: 1,
+                    backend: ref.backend,
+                    platform: slug,
+                    accountId: ref.accountId,
+                };
+                return outcome(await record(ref.deliveryId, target, context, "posts.status"), target, 0);
+            },
+            async cancelScheduled(ref, context) {
+                const row = await record(ref.jobId, ref, context, "posts.cancelScheduled");
+                const scheduledAt = optionalString(row["scheduledAt"]);
+                if (row["status"] !== "SCHEDULED" ||
+                    !scheduledAt ||
+                    !(Date.parse(scheduledAt) > clock().getTime()))
+                    reject("posts.cancelScheduled", "Only a future scheduled post can be cancelled. Reconcile a due or dispatched post.");
+                await remove(ref.jobId, context);
+                return { state: "cancelled", backendRecord: "deleted" };
+            },
+            async deleteBackendRecord(ref, context) {
+                const row = await record(ref.recordId, ref, context, "posts.deleteBackendRecord");
+                if (row["status"] !== "FAILED")
+                    reject("posts.deleteBackendRecord", "PostFast deletes failed records here. Cancel a future schedule explicitly; this never removes a published post.");
+                await remove(ref.recordId, context);
+            },
+        },
+        analytics: {
+            async getPostMetrics(ref, context) {
+                const id = optionalString(ref.native?.["backendRecordId"]);
+                if (!id)
+                    reject("analytics.read", "PostFast metrics need the post reference returned by publish or status reads.");
+                const row = await record(string(id), ref, context, "analytics.read");
+                const publishedAt = optionalString(row["publishedAt"]);
+                if (row["platformPostId"] !== ref.postId || !publishedAt || !Date.parse(publishedAt))
+                    reject("analytics.read", "The PostFast record does not identify this published post.");
+                const published = Date.parse(string(publishedAt));
+                const day = 24 * 60 * 60 * 1000;
+                const result = object(await request("/social-posts/analytics", context, undefined, {
+                    startDate: new Date(published - day).toISOString(),
+                    endDate: new Date(published + day).toISOString(),
+                    socialMediaIds: ref.accountId,
+                }));
+                const match = array(result["data"])
+                    .map(object)
+                    .find((item) => item["id"] === id &&
+                    item["platformPostId"] === ref.postId &&
+                    item["socialMediaId"] === ref.accountId);
+                if (!match || match["latestMetric"] === null || match["latestMetric"] === undefined)
+                    return [];
+                const metrics = object(match["latestMetric"]);
+                const values = [];
+                const push = (name, value, unit) => {
+                    if (value === undefined)
+                        return;
+                    values.push({
+                        name,
+                        value,
+                        unit,
+                        period: "lifetime",
+                        fetchedAt: now(),
+                        freshness: "unknown",
+                        source: `postfast:${ref.platform}:analytics`,
+                    });
+                };
+                for (const [name, key] of [
+                    ["likes", "likes"],
+                    ["comments", "comments"],
+                    ["shares", "shares"],
+                    ["impressions", "impressions"],
+                    ["reach", "reach"],
+                    ["interactions", "totalInteractions"],
+                    ["views", "videoViews"],
+                ])
+                    push(name, count(metrics[key]), "count");
+                push("averageWatchTime", optionalNumber(metrics["avgWatchTimeSeconds"]), "seconds");
+                push("totalWatchTime", optionalNumber(metrics["totalWatchTimeSeconds"]), "seconds");
+                push("saveRate", optionalNumber(metrics["saveRate"]), "percentage");
+                return values;
+            },
+        },
+        native: {
+            /** Create a hosted link where someone connects their social accounts to your workspace. */
+            async createConnectLink(input, context) {
+                for (const value of input.platforms ?? [])
+                    if (!nativePlatforms.has(value))
+                        reject("accounts.connect", "Choose PostFast platforms this adapter supports.");
+                if (input.redirectUrl !== undefined)
+                    httpsUrl(input.redirectUrl);
+                const result = object(await request("/social-media/connect-link", context, {
+                    ...definedFields({
+                        platforms: input.platforms ? [...input.platforms] : undefined,
+                        expiryDays: input.expiryDays,
+                        redirectUrl: input.redirectUrl || undefined,
+                        externalId: input.externalId || undefined,
+                    }),
+                }));
+                return { url: httpsUrl(string(result["connectUrl"])).href };
+            },
+        },
+    });
+    async function remove(id, context) {
+        const result = object(await request(`/social-posts/${encodeURIComponent(id)}`, context, undefined, {}, "DELETE"));
+        if (result["deleted"] !== true)
+            throw new SocialError({
+                code: "ambiguous_outcome",
+                operation: "posts.lifecycle",
+                message: "PostFast did not confirm the deletion. Reconcile before retrying.",
+                retryDisposition: { kind: "reconcile-first" },
+            });
+    }
+    return adapter;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencoredev/social-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Social platform integrations for TypeScript applications.",
   "homepage": "https://github.com/opencoredev/social-sdk#readme",
   "bugs": {
@@ -41,6 +41,10 @@
       "types": "./dist/cloud/post-for-me.d.ts",
       "import": "./dist/cloud/post-for-me.js"
     },
+    "./cloud/postfast": {
+      "types": "./dist/cloud/postfast.d.ts",
+      "import": "./dist/cloud/postfast.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js"