naystack 1.8.12 → 1.8.14

package/dist/socials/meta/container.d.ts

@@ -0,0 +1,38 @@
+import { GraphParams, ContainerState } from './types.js';
+
+/**
+ * Polling settings for a media container.
+ *
+ * @property intervalMS - Delay between status checks. Default: `5000`.
+ * @property timeoutMS - Give up after this long. Default: `300000` (Meta stops processing after ~5 min).
+ *
+ * @category Socials
+ */
+type WaitForContainerOptions = {
+    intervalMS?: number;
+    timeoutMS?: number;
+};
+/**
+ * Wires up the create → wait → publish flow Meta platforms share. Instagram and
+ * Threads differ only in their endpoints, so each builds one publisher and every
+ * post shape goes through it.
+ *
+ * @param platform.name - Used in error logs, e.g. `"Instagram"`.
+ * @param platform.createContainer - Creates a container, resolving to its id.
+ * @param platform.getStatus - Reads a container's state by id.
+ * @param platform.publish - Publishes a finished container, resolving to the post id.
+ * @returns `{ publish, createChildren }`.
+ */
+declare function createPublisher(platform: {
+    name: string;
+    createContainer: (token: string, params: GraphParams) => Promise<string | null>;
+    getStatus: (token: string, id: string) => Promise<ContainerState | null>;
+    publish: (token: string, creationID: string) => Promise<string | null>;
+}): {
+    /** Creates a container, waits for it to finish processing, then publishes it. */
+    publish: (token: string, params: GraphParams, wait?: WaitForContainerOptions) => Promise<string | null>;
+    /** Creates and awaits every carousel child, resolving to their ids — or `null` if any failed. */
+    createChildren: (token: string, items: GraphParams[], wait?: WaitForContainerOptions) => Promise<string[] | null>;
+};
+
+export { type WaitForContainerOptions, createPublisher };

package/dist/socials/meta/container.esm.js

@@ -0,0 +1,57 @@
+// src/socials/meta/container.ts
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function waitForContainer(getState, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
+  const deadline = Date.now() + timeoutMS;
+  let state = await getState();
+  if (!state) {
+    await sleep(2e3);
+    return null;
+  }
+  while (state?.status === "IN_PROGRESS" && Date.now() < deadline) {
+    await sleep(intervalMS);
+    state = await getState();
+  }
+  return state;
+}
+function createPublisher(platform) {
+  const isReady = async (token, id, label, wait) => {
+    const state = await waitForContainer(
+      () => platform.getStatus(token, id),
+      wait
+    );
+    if (state && state.status !== "FINISHED" && state.status !== "PUBLISHED") {
+      console.error(
+        `[naystack] ${platform.name} ${label} ${id} is ${state.status}${state.error ? `: ${state.error}` : ""}`
+      );
+      return false;
+    }
+    return true;
+  };
+  return {
+    /** Creates a container, waits for it to finish processing, then publishes it. */
+    publish: async (token, params, wait) => {
+      const containerID = await platform.createContainer(token, params);
+      if (!containerID) return null;
+      if (!await isReady(token, containerID, "container", wait)) return null;
+      return platform.publish(token, containerID);
+    },
+    /** Creates and awaits every carousel child, resolving to their ids — or `null` if any failed. */
+    createChildren: async (token, items, wait) => {
+      const children = [];
+      for (const item of items) {
+        const childID = await platform.createContainer(token, {
+          ...item,
+          is_carousel_item: true
+        });
+        if (!childID) return null;
+        if (!await isReady(token, childID, "carousel item", wait))
+          return null;
+        children.push(childID);
+      }
+      return children;
+    }
+  };
+}
+export {
+  createPublisher
+};

package/dist/socials/meta/request.cjs.js

@@ -0,0 +1,60 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/socials/meta/request.ts
+var request_exports = {};
+__export(request_exports, {
+  createGraphClient: () => createGraphClient,
+  readGraphID: () => readGraphID
+});
+module.exports = __toCommonJS(request_exports);
+function createGraphClient(baseURL) {
+  const buildURL = (token, path, params = {}) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    search.set("access_token", token);
+    return `${baseURL}/${path}?${search.toString()}`;
+  };
+  const request = async (token, path, options = {}) => {
+    const response = await fetch(buildURL(token, path, options.params), {
+      method: options.method || (options.body ? "POST" : "GET"),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      ...options.body ? { body: JSON.stringify(options.body) } : {}
+    });
+    return response.json().catch(() => null);
+  };
+  return { buildURL, request };
+}
+function readGraphID(label, result) {
+  if (result?.error) {
+    console.error(`[naystack] ${label} failed: ${result.error.message}`);
+    return null;
+  }
+  return result?.id || null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGraphClient,
+  readGraphID
+});

package/dist/socials/meta/request.d.mts

@@ -0,0 +1,50 @@
+import { GraphParams, GraphError } from './types.mjs';
+
+/**
+ * Options for a single Graph API request.
+ *
+ * @property params - Query parameters. Most Graph mutations take their arguments here, not in a body.
+ * @property method - Defaults to `"POST"` when `body` is set, `"GET"` otherwise.
+ * @property body - JSON body, for the few endpoints that need one (e.g. Instagram messaging).
+ *
+ * @category Socials
+ */
+type GraphRequestOptions = {
+    params?: GraphParams;
+    method?: "GET" | "POST";
+    body?: object;
+};
+/**
+ * A Graph API client bound to one platform's base URL.
+ *
+ * @category Socials
+ */
+type GraphClient = {
+    buildURL: (token: string, path: string, params?: GraphParams) => string;
+    request: <T>(token: string, path: string, options?: GraphRequestOptions) => Promise<(T & GraphError) | null>;
+};
+/**
+ * Creates a Graph API client for a base URL (Instagram, Threads — same protocol,
+ * different host and version).
+ *
+ * Every param is URL-encoded, so captions may contain spaces, `&`, `#` and newlines.
+ *
+ * @param baseURL - Versioned API root, e.g. `"https://graph.instagram.com/v23.0"`.
+ * @returns `{ buildURL, request }`.
+ * @category Socials
+ */
+declare function createGraphClient(baseURL: string): GraphClient;
+/**
+ * Unwraps the `id` from a Graph API response, logging the API's own message
+ * when the call failed. Keeps publishing helpers to a single `null` return.
+ *
+ * @param label - Name used in the error log, e.g. `"Instagram media container"`.
+ * @param result - Raw Graph API response.
+ * @returns The id, or `null` on error.
+ * @category Socials
+ */
+declare function readGraphID(label: string, result: ({
+    id?: string;
+} & GraphError) | null): string | null;
+
+export { type GraphClient, type GraphRequestOptions, createGraphClient, readGraphID };

package/dist/socials/meta/request.d.ts

@@ -0,0 +1,50 @@
+import { GraphParams, GraphError } from './types.js';
+
+/**
+ * Options for a single Graph API request.
+ *
+ * @property params - Query parameters. Most Graph mutations take their arguments here, not in a body.
+ * @property method - Defaults to `"POST"` when `body` is set, `"GET"` otherwise.
+ * @property body - JSON body, for the few endpoints that need one (e.g. Instagram messaging).
+ *
+ * @category Socials
+ */
+type GraphRequestOptions = {
+    params?: GraphParams;
+    method?: "GET" | "POST";
+    body?: object;
+};
+/**
+ * A Graph API client bound to one platform's base URL.
+ *
+ * @category Socials
+ */
+type GraphClient = {
+    buildURL: (token: string, path: string, params?: GraphParams) => string;
+    request: <T>(token: string, path: string, options?: GraphRequestOptions) => Promise<(T & GraphError) | null>;
+};
+/**
+ * Creates a Graph API client for a base URL (Instagram, Threads — same protocol,
+ * different host and version).
+ *
+ * Every param is URL-encoded, so captions may contain spaces, `&`, `#` and newlines.
+ *
+ * @param baseURL - Versioned API root, e.g. `"https://graph.instagram.com/v23.0"`.
+ * @returns `{ buildURL, request }`.
+ * @category Socials
+ */
+declare function createGraphClient(baseURL: string): GraphClient;
+/**
+ * Unwraps the `id` from a Graph API response, logging the API's own message
+ * when the call failed. Keeps publishing helpers to a single `null` return.
+ *
+ * @param label - Name used in the error log, e.g. `"Instagram media container"`.
+ * @param result - Raw Graph API response.
+ * @returns The id, or `null` on error.
+ * @category Socials
+ */
+declare function readGraphID(label: string, result: ({
+    id?: string;
+} & GraphError) | null): string | null;
+
+export { type GraphClient, type GraphRequestOptions, createGraphClient, readGraphID };

package/dist/socials/meta/request.esm.js

@@ -0,0 +1,34 @@
+// src/socials/meta/request.ts
+function createGraphClient(baseURL) {
+  const buildURL = (token, path, params = {}) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    search.set("access_token", token);
+    return `${baseURL}/${path}?${search.toString()}`;
+  };
+  const request = async (token, path, options = {}) => {
+    const response = await fetch(buildURL(token, path, options.params), {
+      method: options.method || (options.body ? "POST" : "GET"),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      ...options.body ? { body: JSON.stringify(options.body) } : {}
+    });
+    return response.json().catch(() => null);
+  };
+  return { buildURL, request };
+}
+function readGraphID(label, result) {
+  if (result?.error) {
+    console.error(`[naystack] ${label} failed: ${result.error.message}`);
+    return null;
+  }
+  return result?.id || null;
+}
+export {
+  createGraphClient,
+  readGraphID
+};

package/dist/socials/meta/types.cjs.js

@@ -0,0 +1,34 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/socials/meta/types.ts
+var types_exports = {};
+__export(types_exports, {
+  MetaMediaType: () => MetaMediaType
+});
+module.exports = __toCommonJS(types_exports);
+var MetaMediaType = /* @__PURE__ */ ((MetaMediaType2) => {
+  MetaMediaType2["Photo"] = "photo";
+  MetaMediaType2["Video"] = "video";
+  return MetaMediaType2;
+})(MetaMediaType || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MetaMediaType
+});

package/dist/socials/meta/types.d.mts

@@ -0,0 +1,51 @@
+/**
+ * Types for Meta's Graph protocol — the request/response shape Instagram and
+ * Threads share. Platforms outside Meta don't use these.
+ *
+ * @module
+ */
+/**
+ * Query parameters for a Graph API request. Values are stringified and URL-encoded;
+ * `undefined` entries are dropped, so optional params can be passed inline.
+ *
+ * @category Socials
+ */
+type GraphParams = Record<string, string | number | boolean | undefined>;
+/**
+ * Meta Graph API error response shape (Instagram, Threads).
+ *
+ * @property error - Error details from the API (message, type, code, subcode, trace id).
+ *
+ * @category Socials
+ */
+type GraphError = {
+    error?: {
+        message: string;
+        type: string;
+        code: number;
+        error_subcode: number;
+        fbtrace_id: string;
+    };
+};
+/**
+ * Processing status of a media container, before it can be published.
+ * Shared vocabulary across Instagram (`status_code`) and Threads (`status`).
+ *
+ * @category Socials
+ */
+type ContainerStatus = "EXPIRED" | "ERROR" | "FINISHED" | "IN_PROGRESS" | "PUBLISHED";
+/**
+ * A container's processing status plus the API's reason when it failed.
+ *
+ * @category Socials
+ */
+type ContainerState = {
+    status: ContainerStatus;
+    error?: string;
+};
+declare enum MetaMediaType {
+    Photo = "photo",
+    Video = "video"
+}
+
+export { type ContainerState, type ContainerStatus, type GraphError, type GraphParams, MetaMediaType };

package/dist/socials/meta/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Types for Meta's Graph protocol — the request/response shape Instagram and
+ * Threads share. Platforms outside Meta don't use these.
+ *
+ * @module
+ */
+/**
+ * Query parameters for a Graph API request. Values are stringified and URL-encoded;
+ * `undefined` entries are dropped, so optional params can be passed inline.
+ *
+ * @category Socials
+ */
+type GraphParams = Record<string, string | number | boolean | undefined>;
+/**
+ * Meta Graph API error response shape (Instagram, Threads).
+ *
+ * @property error - Error details from the API (message, type, code, subcode, trace id).
+ *
+ * @category Socials
+ */
+type GraphError = {
+    error?: {
+        message: string;
+        type: string;
+        code: number;
+        error_subcode: number;
+        fbtrace_id: string;
+    };
+};
+/**
+ * Processing status of a media container, before it can be published.
+ * Shared vocabulary across Instagram (`status_code`) and Threads (`status`).
+ *
+ * @category Socials
+ */
+type ContainerStatus = "EXPIRED" | "ERROR" | "FINISHED" | "IN_PROGRESS" | "PUBLISHED";
+/**
+ * A container's processing status plus the API's reason when it failed.
+ *
+ * @category Socials
+ */
+type ContainerState = {
+    status: ContainerStatus;
+    error?: string;
+};
+declare enum MetaMediaType {
+    Photo = "photo",
+    Video = "video"
+}
+
+export { type ContainerState, type ContainerStatus, type GraphError, type GraphParams, MetaMediaType };

package/dist/socials/meta/types.esm.js

@@ -0,0 +1,9 @@
+// src/socials/meta/types.ts
+var MetaMediaType = /* @__PURE__ */ ((MetaMediaType2) => {
+  MetaMediaType2["Photo"] = "photo";
+  MetaMediaType2["Video"] = "video";
+  return MetaMediaType2;
+})(MetaMediaType || {});
+export {
+  MetaMediaType
+};

package/dist/socials/{meta-webhook.cjs.js → meta/webhook.cjs.js}

@@ -17,12 +17,12 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/socials/meta-webhook.ts
-var meta_webhook_exports = {};
-__export(meta_webhook_exports, {
+// src/socials/meta/webhook.ts
+var webhook_exports = {};
+__export(webhook_exports, {
   verifyWebhook: () => verifyWebhook
 });
-module.exports = __toCommonJS(meta_webhook_exports);
+module.exports = __toCommonJS(webhook_exports);
 var import_server = require("next/server");
 var verifyWebhook = (secret) => (req) => {
   const params = req.nextUrl.searchParams;

package/dist/socials/{meta-webhook.esm.js → meta/webhook.esm.js}

@@ -1,4 +1,4 @@
-// src/socials/meta-webhook.ts
+// src/socials/meta/webhook.ts
 import { NextResponse } from "next/server";
 var verifyWebhook = (secret) => (req) => {
   const params = req.nextUrl.searchParams;

package/dist/socials/threads/getters.cjs.js

@@ -22,39 +22,64 @@ var getters_exports = {};
 __export(getters_exports, {
   getThread: () => getThread,
   getThreads: () => getThreads,
+  getThreadsContainerStatus: () => getThreadsContainerStatus,
   getThreadsReplies: () => getThreadsReplies
 });
 module.exports = __toCommonJS(getters_exports);
 
-// src/socials/threads/utils.ts
-function getThreadsURL(token, path, params) {
-  return `https://graph.threads.net/v1.0/${path}?${Object.keys(params).map((key) => `${key}=${params[key]}`).join("&")}&access_token=${token}`;
-}
-function getThreadsData(token, path, params, method) {
-  return fetch(getThreadsURL(token, path, params), {
-    method: method || "GET"
-  }).then((res) => res.json());
+// src/socials/meta/request.ts
+function createGraphClient(baseURL) {
+  const buildURL = (token, path, params = {}) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) search.set(key, String(value));
+    }
+    search.set("access_token", token);
+    return `${baseURL}/${path}?${search.toString()}`;
+  };
+  const request = async (token, path, options = {}) => {
+    const response = await fetch(buildURL(token, path, options.params), {
+      method: options.method || (options.body ? "POST" : "GET"),
+      headers: {
+        Authorization: `Bearer ${token}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      ...options.body ? { body: JSON.stringify(options.body) } : {}
+    });
+    return response.json().catch(() => null);
+  };
+  return { buildURL, request };
 }
 
+// src/socials/threads/utils.ts
+var client = createGraphClient("https://graph.threads.net/v1.0");
+var getThreadsData = client.request;
+
 // src/socials/threads/getters.ts
 var getThread = (token, id, fields) => {
   return getThreadsData(token, id, {
-    fields: fields ? fields.join(",") : "text,permalink,username"
+    params: { fields: fields ? fields.join(",") : "text,permalink,username" }
   });
 };
 var getThreads = (token, fields) => {
   return getThreadsData(token, "me/threads", {
-    fields: fields ? fields.join(",") : "text,permalink,username"
+    params: { fields: fields ? fields.join(",") : "text,permalink,username" }
   }).then((res) => res?.data);
 };
 var getThreadsReplies = (token, id, fields) => {
   return getThreadsData(token, `${id}/replies`, {
-    fields: fields ? fields.join(",") : "text,username,permalink"
+    params: { fields: fields ? fields.join(",") : "text,username,permalink" }
   }).then((res) => res?.data);
 };
+var getThreadsContainerStatus = async (token, id) => {
+  const result = await getThreadsData(token, id, { params: { fields: "status,error_message" } });
+  if (!result?.status) return null;
+  return { status: result.status, error: result.error_message };
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   getThread,
   getThreads,
+  getThreadsContainerStatus,
   getThreadsReplies
 });

package/dist/socials/threads/getters.d.mts

@@ -1,4 +1,6 @@
+import { GraphError, ContainerState } from '../meta/types.mjs';
 import { ThreadsPost } from './types.mjs';
+import '../meta/container.mjs';
 
 /**
  * Fetches a single Threads post by id.
@@ -18,7 +20,7 @@ import { ThreadsPost } from './types.mjs';
  *
  * @category Socials
  */
-declare const getThread: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T | null>;
+declare const getThread: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<(T & GraphError) | null>;
 /**
  * Fetches the authenticated user's Threads posts.
  *
@@ -60,5 +62,24 @@ declare const getThreads: <T = ThreadsPost>(token: string, fields?: string[]) =>
  * @category Socials
  */
 declare const getThreadsReplies: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T[] | undefined>;
+/**
+ * Reads a media container's processing status. Image, video and carousel
+ * containers must reach `FINISHED` before they can be published.
+ *
+ * @param token - Threads access token.
+ * @param id - Container id from `createThreadsContainer`.
+ * @returns Promise of `{ status, error? }`, or `null` if the status was unreadable.
+ *
+ * @example
+ * ```ts
+ * import { getThreadsContainerStatus } from "naystack/socials";
+ *
+ * const state = await getThreadsContainerStatus(accessToken, containerId);
+ * if (state?.status === "FINISHED") await publishThreadsContainer(accessToken, containerId);
+ * ```
+ *
+ * @category Socials
+ */
+declare const getThreadsContainerStatus: (token: string, id: string) => Promise<ContainerState | null>;
 
-export { getThread, getThreads, getThreadsReplies };
+export { getThread, getThreads, getThreadsContainerStatus, getThreadsReplies };

package/dist/socials/threads/getters.d.ts

@@ -1,4 +1,6 @@
+import { GraphError, ContainerState } from '../meta/types.js';
 import { ThreadsPost } from './types.js';
+import '../meta/container.js';
 
 /**
  * Fetches a single Threads post by id.
@@ -18,7 +20,7 @@ import { ThreadsPost } from './types.js';
  *
  * @category Socials
  */
-declare const getThread: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T | null>;
+declare const getThread: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<(T & GraphError) | null>;
 /**
  * Fetches the authenticated user's Threads posts.
  *
@@ -60,5 +62,24 @@ declare const getThreads: <T = ThreadsPost>(token: string, fields?: string[]) =>
  * @category Socials
  */
 declare const getThreadsReplies: <T = ThreadsPost>(token: string, id: string, fields?: string[]) => Promise<T[] | undefined>;
+/**
+ * Reads a media container's processing status. Image, video and carousel
+ * containers must reach `FINISHED` before they can be published.
+ *
+ * @param token - Threads access token.
+ * @param id - Container id from `createThreadsContainer`.
+ * @returns Promise of `{ status, error? }`, or `null` if the status was unreadable.
+ *
+ * @example
+ * ```ts
+ * import { getThreadsContainerStatus } from "naystack/socials";
+ *
+ * const state = await getThreadsContainerStatus(accessToken, containerId);
+ * if (state?.status === "FINISHED") await publishThreadsContainer(accessToken, containerId);
+ * ```
+ *
+ * @category Socials
+ */
+declare const getThreadsContainerStatus: (token: string, id: string) => Promise<ContainerState | null>;
 
-export { getThread, getThreads, getThreadsReplies };
+export { getThread, getThreads, getThreadsContainerStatus, getThreadsReplies };