naystack 1.8.19 → 1.9.1

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

@@ -25,25 +25,42 @@ __export(setters_exports, {
 });
 module.exports = __toCommonJS(setters_exports);
 
-// src/socials/meta/container.ts
+// src/socials/utils/poll.ts
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function waitForContainer(getState, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
+async function pollUntilReady(read, isPending, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
   const deadline = Date.now() + timeoutMS;
-  let state = await getState();
+  let state = await read();
   if (!state) {
     await sleep(2e3);
     return null;
   }
-  while (state?.status === "IN_PROGRESS" && Date.now() < deadline) {
+  while (state && isPending(state) && Date.now() < deadline) {
     await sleep(intervalMS);
-    state = await getState();
+    state = await read();
   }
   return state;
 }
+async function withRetry(run, options = {}) {
+  const attempts = Math.max(1, options.attempts ?? 3);
+  const backoffMS = options.backoffMS ?? 2e3;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const result = await run(attempt);
+    if (result) return result;
+    if (attempt < attempts) {
+      const delayMS = backoffMS * 2 ** (attempt - 1);
+      options.onRetry?.(attempt, attempts, delayMS);
+      await sleep(delayMS);
+    }
+  }
+  return null;
+}
+
+// src/socials/meta/container.ts
 function createPublisher(platform) {
   const isReady = async (token, id, label, wait) => {
-    const state = await waitForContainer(
+    const state = await pollUntilReady(
       () => platform.getStatus(token, id),
+      (current) => current.status === "IN_PROGRESS",
       wait
     );
     if (state && state.status !== "FINISHED" && state.status !== "PUBLISHED") {
@@ -54,22 +71,21 @@ function createPublisher(platform) {
     }
     return true;
   };
-  const createReady = async (token, params, label, wait, retry) => {
-    const attempts = Math.max(1, retry?.attempts ?? 3);
-    const backoffMS = retry?.backoffMS ?? 2e3;
-    for (let attempt = 1; attempt <= attempts; attempt++) {
+  const createReady = (token, params, label, wait, retry) => withRetry(
+    async () => {
       const id = await platform.createContainer(token, params);
-      if (id && await isReady(token, id, label, wait)) return id;
-      if (attempt < attempts) {
-        const delay = backoffMS * 2 ** (attempt - 1);
+      if (!id || !await isReady(token, id, label, wait)) return null;
+      return id;
+    },
+    {
+      ...retry,
+      onRetry: (attempt, attempts, delayMS) => {
         console.warn(
-          `[naystack] ${platform.name} ${label} attempt ${attempt}/${attempts} failed \u2014 retrying in ${delay}ms`
+          `[naystack] ${platform.name} ${label} attempt ${attempt}/${attempts} failed \u2014 retrying in ${delayMS}ms`
         );
-        await sleep(delay);
       }
     }
-    return null;
-  };
+  );
   return {
     /** Creates a container, waits for it to finish processing, then publishes it. */
     publish: async (token, params, wait, retry) => {

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

@@ -1,6 +1,7 @@
 import { ThreadsPostInput } from './types.mjs';
 import '../meta/container.mjs';
 import '../meta/types.mjs';
+import '../utils/poll.mjs';
 
 /**
  * Publishes to Threads — text, image, video or carousel, chosen from the media you

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

@@ -1,6 +1,7 @@
 import { ThreadsPostInput } from './types.js';
 import '../meta/container.js';
 import '../meta/types.js';
+import '../utils/poll.js';
 
 /**
  * Publishes to Threads — text, image, video or carousel, chosen from the media you

package/dist/socials/threads/setters.esm.js

@@ -1,22 +1,39 @@
-// src/socials/meta/container.ts
+// src/socials/utils/poll.ts
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-async function waitForContainer(getState, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
+async function pollUntilReady(read, isPending, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
   const deadline = Date.now() + timeoutMS;
-  let state = await getState();
+  let state = await read();
   if (!state) {
     await sleep(2e3);
     return null;
   }
-  while (state?.status === "IN_PROGRESS" && Date.now() < deadline) {
+  while (state && isPending(state) && Date.now() < deadline) {
     await sleep(intervalMS);
-    state = await getState();
+    state = await read();
   }
   return state;
 }
+async function withRetry(run, options = {}) {
+  const attempts = Math.max(1, options.attempts ?? 3);
+  const backoffMS = options.backoffMS ?? 2e3;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const result = await run(attempt);
+    if (result) return result;
+    if (attempt < attempts) {
+      const delayMS = backoffMS * 2 ** (attempt - 1);
+      options.onRetry?.(attempt, attempts, delayMS);
+      await sleep(delayMS);
+    }
+  }
+  return null;
+}
+
+// src/socials/meta/container.ts
 function createPublisher(platform) {
   const isReady = async (token, id, label, wait) => {
-    const state = await waitForContainer(
+    const state = await pollUntilReady(
       () => platform.getStatus(token, id),
+      (current) => current.status === "IN_PROGRESS",
       wait
     );
     if (state && state.status !== "FINISHED" && state.status !== "PUBLISHED") {
@@ -27,22 +44,21 @@ function createPublisher(platform) {
     }
     return true;
   };
-  const createReady = async (token, params, label, wait, retry) => {
-    const attempts = Math.max(1, retry?.attempts ?? 3);
-    const backoffMS = retry?.backoffMS ?? 2e3;
-    for (let attempt = 1; attempt <= attempts; attempt++) {
+  const createReady = (token, params, label, wait, retry) => withRetry(
+    async () => {
       const id = await platform.createContainer(token, params);
-      if (id && await isReady(token, id, label, wait)) return id;
-      if (attempt < attempts) {
-        const delay = backoffMS * 2 ** (attempt - 1);
+      if (!id || !await isReady(token, id, label, wait)) return null;
+      return id;
+    },
+    {
+      ...retry,
+      onRetry: (attempt, attempts, delayMS) => {
         console.warn(
-          `[naystack] ${platform.name} ${label} attempt ${attempt}/${attempts} failed \u2014 retrying in ${delay}ms`
+          `[naystack] ${platform.name} ${label} attempt ${attempt}/${attempts} failed \u2014 retrying in ${delayMS}ms`
         );
-        await sleep(delay);
       }
     }
-    return null;
-  };
+  );
   return {
     /** Creates a container, waits for it to finish processing, then publishes it. */
     publish: async (token, params, wait, retry) => {

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

@@ -1,5 +1,6 @@
-import { WaitForContainerOptions, RetryOptions } from '../meta/container.mjs';
+import { WaitForContainerOptions } from '../meta/container.mjs';
 import { MetaMediaType } from '../meta/types.mjs';
+import { RetryOptions } from '../utils/poll.mjs';
 
 /**
  * Threads post (single post or reply).

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

@@ -1,5 +1,6 @@
-import { WaitForContainerOptions, RetryOptions } from '../meta/container.js';
+import { WaitForContainerOptions } from '../meta/container.js';
 import { MetaMediaType } from '../meta/types.js';
+import { RetryOptions } from '../utils/poll.js';
 
 /**
  * Threads post (single post or reply).

package/dist/socials/types.cjs.js

@@ -0,0 +1,43 @@
+"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/types.ts
+var types_exports = {};
+__export(types_exports, {
+  SocialMediaKind: () => SocialMediaKind,
+  SocialPlatform: () => SocialPlatform
+});
+module.exports = __toCommonJS(types_exports);
+var SocialPlatform = /* @__PURE__ */ ((SocialPlatform2) => {
+  SocialPlatform2["Instagram"] = "instagram";
+  SocialPlatform2["YouTube"] = "youtube";
+  SocialPlatform2["TikTok"] = "tiktok";
+  return SocialPlatform2;
+})(SocialPlatform || {});
+var SocialMediaKind = /* @__PURE__ */ ((SocialMediaKind2) => {
+  SocialMediaKind2["Image"] = "image";
+  SocialMediaKind2["Video"] = "video";
+  SocialMediaKind2["Carousel"] = "carousel";
+  return SocialMediaKind2;
+})(SocialMediaKind || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SocialMediaKind,
+  SocialPlatform
+});

package/dist/socials/types.d.mts

@@ -0,0 +1,99 @@
+/**
+ * Platform-neutral shapes every social provider maps its API onto: one row for a
+ * connected account, one for a piece of its content. Raw per-platform payloads
+ * (`InstagramUser`, `ThreadsPost`, …) stay available for anything these flatten.
+ *
+ * @module
+ */
+/**
+ * A platform a user can connect an account on. Values double as URL path
+ * segments, so a route mounted at `/api/social/[platform]` matches them verbatim.
+ *
+ * @category Socials
+ */
+declare enum SocialPlatform {
+    Instagram = "instagram",
+    YouTube = "youtube",
+    TikTok = "tiktok"
+}
+/**
+ * What a piece of content is. Each adapter maps its platform's own vocabulary
+ * (Instagram's uppercase `IMAGE` / `VIDEO` / `CAROUSEL_ALBUM`, a reel being a
+ * `VIDEO`) onto these three.
+ *
+ * @category Socials
+ */
+declare enum SocialMediaKind {
+    Image = "image",
+    Video = "video",
+    Carousel = "carousel"
+}
+/**
+ * A connected account's profile and audience.
+ *
+ * @property platformUserId - The platform's own id. Stable across renames — key on it, not `username`. `null` when the platform doesn't return one.
+ * @property username - Public handle. Mutable, and a freed handle can be taken by someone else.
+ * @property avatar - Usually a signed CDN URL that expires; copy it to your own storage.
+ * @property followers - Subscribers on YouTube, followers elsewhere.
+ * @property metadata - Platform extras, display-only: keys differ per platform, so never filter or sort on them.
+ *
+ * @category Socials
+ */
+type SocialProfile = {
+    platform: SocialPlatform;
+    platformUserId: string | null;
+    username: string;
+    displayName: string | null;
+    avatar: string | null;
+    followers: number;
+    contentCount: number;
+    metadata: Record<string, unknown>;
+};
+/**
+ * One piece of content from a connected account.
+ *
+ * Every metric is `number | null`, and `null` always means *the platform did not
+ * give us this* — hidden, unrequested, or nonexistent on that platform. Adapters
+ * never substitute `0`: "nobody liked it" and "likes are hidden" are different
+ * facts, and only the caller knows which its averages should skip.
+ *
+ * @property platformMediaId - Unique within a platform, not across them.
+ * @property thumbnail - Usually a signed CDN URL that expires; copy it to your own storage.
+ * @property publishedAt - ISO 8601.
+ * @property metadata - Platform extras, display-only, same contract as {@link SocialProfile}.
+ *
+ * @category Socials
+ */
+type SocialPost = {
+    platform: SocialPlatform;
+    platformMediaId: string;
+    permalink: string;
+    thumbnail: string | null;
+    mediaURL: string | null;
+    caption: string | null;
+    kind: SocialMediaKind;
+    publishedAt: string;
+    likes: number | null;
+    comments: number | null;
+    views: number | null;
+    shares: number | null;
+    metadata: Record<string, unknown>;
+};
+/**
+ * Credentials for a connected account. Instagram issues a long-lived
+ * `accessToken` refreshed in place; Google and TikTok pair a short one with a
+ * `refreshToken`. One shape covers both.
+ *
+ * @property expiresAt - Absent when the platform doesn't say.
+ * @property scopes - Permissions actually granted. A token can be valid yet lack the scope for a given call.
+ *
+ * @category Socials
+ */
+type SocialTokens = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: Date;
+    scopes?: string[];
+};
+
+export { SocialMediaKind, SocialPlatform, type SocialPost, type SocialProfile, type SocialTokens };

package/dist/socials/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Platform-neutral shapes every social provider maps its API onto: one row for a
+ * connected account, one for a piece of its content. Raw per-platform payloads
+ * (`InstagramUser`, `ThreadsPost`, …) stay available for anything these flatten.
+ *
+ * @module
+ */
+/**
+ * A platform a user can connect an account on. Values double as URL path
+ * segments, so a route mounted at `/api/social/[platform]` matches them verbatim.
+ *
+ * @category Socials
+ */
+declare enum SocialPlatform {
+    Instagram = "instagram",
+    YouTube = "youtube",
+    TikTok = "tiktok"
+}
+/**
+ * What a piece of content is. Each adapter maps its platform's own vocabulary
+ * (Instagram's uppercase `IMAGE` / `VIDEO` / `CAROUSEL_ALBUM`, a reel being a
+ * `VIDEO`) onto these three.
+ *
+ * @category Socials
+ */
+declare enum SocialMediaKind {
+    Image = "image",
+    Video = "video",
+    Carousel = "carousel"
+}
+/**
+ * A connected account's profile and audience.
+ *
+ * @property platformUserId - The platform's own id. Stable across renames — key on it, not `username`. `null` when the platform doesn't return one.
+ * @property username - Public handle. Mutable, and a freed handle can be taken by someone else.
+ * @property avatar - Usually a signed CDN URL that expires; copy it to your own storage.
+ * @property followers - Subscribers on YouTube, followers elsewhere.
+ * @property metadata - Platform extras, display-only: keys differ per platform, so never filter or sort on them.
+ *
+ * @category Socials
+ */
+type SocialProfile = {
+    platform: SocialPlatform;
+    platformUserId: string | null;
+    username: string;
+    displayName: string | null;
+    avatar: string | null;
+    followers: number;
+    contentCount: number;
+    metadata: Record<string, unknown>;
+};
+/**
+ * One piece of content from a connected account.
+ *
+ * Every metric is `number | null`, and `null` always means *the platform did not
+ * give us this* — hidden, unrequested, or nonexistent on that platform. Adapters
+ * never substitute `0`: "nobody liked it" and "likes are hidden" are different
+ * facts, and only the caller knows which its averages should skip.
+ *
+ * @property platformMediaId - Unique within a platform, not across them.
+ * @property thumbnail - Usually a signed CDN URL that expires; copy it to your own storage.
+ * @property publishedAt - ISO 8601.
+ * @property metadata - Platform extras, display-only, same contract as {@link SocialProfile}.
+ *
+ * @category Socials
+ */
+type SocialPost = {
+    platform: SocialPlatform;
+    platformMediaId: string;
+    permalink: string;
+    thumbnail: string | null;
+    mediaURL: string | null;
+    caption: string | null;
+    kind: SocialMediaKind;
+    publishedAt: string;
+    likes: number | null;
+    comments: number | null;
+    views: number | null;
+    shares: number | null;
+    metadata: Record<string, unknown>;
+};
+/**
+ * Credentials for a connected account. Instagram issues a long-lived
+ * `accessToken` refreshed in place; Google and TikTok pair a short one with a
+ * `refreshToken`. One shape covers both.
+ *
+ * @property expiresAt - Absent when the platform doesn't say.
+ * @property scopes - Permissions actually granted. A token can be valid yet lack the scope for a given call.
+ *
+ * @category Socials
+ */
+type SocialTokens = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: Date;
+    scopes?: string[];
+};
+
+export { SocialMediaKind, SocialPlatform, type SocialPost, type SocialProfile, type SocialTokens };

package/dist/socials/types.esm.js

@@ -0,0 +1,17 @@
+// src/socials/types.ts
+var SocialPlatform = /* @__PURE__ */ ((SocialPlatform2) => {
+  SocialPlatform2["Instagram"] = "instagram";
+  SocialPlatform2["YouTube"] = "youtube";
+  SocialPlatform2["TikTok"] = "tiktok";
+  return SocialPlatform2;
+})(SocialPlatform || {});
+var SocialMediaKind = /* @__PURE__ */ ((SocialMediaKind2) => {
+  SocialMediaKind2["Image"] = "image";
+  SocialMediaKind2["Video"] = "video";
+  SocialMediaKind2["Carousel"] = "carousel";
+  return SocialMediaKind2;
+})(SocialMediaKind || {});
+export {
+  SocialMediaKind,
+  SocialPlatform
+};

package/dist/socials/utils/poll.cjs.js

@@ -0,0 +1,59 @@
+"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/utils/poll.ts
+var poll_exports = {};
+__export(poll_exports, {
+  pollUntilReady: () => pollUntilReady,
+  withRetry: () => withRetry
+});
+module.exports = __toCommonJS(poll_exports);
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function pollUntilReady(read, isPending, { intervalMS = 5e3, timeoutMS = 3e5 } = {}) {
+  const deadline = Date.now() + timeoutMS;
+  let state = await read();
+  if (!state) {
+    await sleep(2e3);
+    return null;
+  }
+  while (state && isPending(state) && Date.now() < deadline) {
+    await sleep(intervalMS);
+    state = await read();
+  }
+  return state;
+}
+async function withRetry(run, options = {}) {
+  const attempts = Math.max(1, options.attempts ?? 3);
+  const backoffMS = options.backoffMS ?? 2e3;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const result = await run(attempt);
+    if (result) return result;
+    if (attempt < attempts) {
+      const delayMS = backoffMS * 2 ** (attempt - 1);
+      options.onRetry?.(attempt, attempts, delayMS);
+      await sleep(delayMS);
+    }
+  }
+  return null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  pollUntilReady,
+  withRetry
+});

package/dist/socials/utils/poll.d.mts

@@ -0,0 +1,85 @@
+/**
+ * Waiting and retrying, with no platform in them. Meta's media containers were
+ * the first caller; any API that hands back a job id and a status endpoint wants
+ * the same two helpers.
+ *
+ * @module
+ */
+/**
+ * Polling settings for {@link pollUntilReady}.
+ *
+ * @property intervalMS - Delay between reads. Default: `5000`.
+ * @property timeoutMS - Stop polling after this long. Default: `300000`.
+ *
+ * @category Socials
+ */
+type PollOptions = {
+    intervalMS?: number;
+    timeoutMS?: number;
+};
+/**
+ * Retry settings for {@link withRetry}.
+ *
+ * @property attempts - Total tries, including the first. Default: `3`.
+ * @property backoffMS - Delay before the second try, doubled each time after. Default: `2000`.
+ *
+ * @category Socials
+ */
+type RetryOptions = {
+    attempts?: number;
+    backoffMS?: number;
+};
+/**
+ * Reads a job's state until it stops being pending.
+ *
+ * Resolves `null` when the first read returns nothing. That is "unknown", not
+ * "failed": some jobs are complete the moment they exist and never publish a
+ * readable status, so treating `null` as an error would reject work that already
+ * succeeded. A short pause before returning gives such a job a beat to settle.
+ *
+ * @param read - `null` means no state was readable.
+ * @param isPending - `true` while the state means "still working".
+ * @returns The last state read, or `null` if the state was never readable.
+ *
+ * @example
+ * ```ts
+ * import { pollUntilReady } from "naystack/socials";
+ *
+ * const state = await pollUntilReady(
+ *   () => getInstagramContainerStatus(token, containerID),
+ *   (s) => s.status === "IN_PROGRESS",
+ * );
+ * ```
+ *
+ * @category Socials
+ */
+declare function pollUntilReady<T>(read: () => Promise<T | null>, isPending: (state: T) => boolean, { intervalMS, timeoutMS }?: PollOptions): Promise<T | null>;
+/**
+ * Runs an operation until it produces a result, backing off between tries.
+ *
+ * `run` signals failure by resolving `null` rather than throwing — the socials
+ * helpers log the API's message and resolve `null`, so a loop that only caught
+ * exceptions would never retry.
+ *
+ * @param run - Receives the 1-based attempt number; resolve `null` to retry.
+ * @param options - {@link RetryOptions}, plus `onRetry` for logging before each delay.
+ * @returns The first non-`null` result, or `null` once every attempt is spent.
+ *
+ * @example
+ * ```ts
+ * import { withRetry } from "naystack/socials";
+ *
+ * const id = await withRetry(() => createContainer(token, params), {
+ *   attempts: 3,
+ *   onRetry: (attempt, attempts, delayMS) =>
+ *     console.warn(`attempt ${attempt}/${attempts} failed — retrying in ${delayMS}ms`),
+ * });
+ * ```
+ *
+ * @category Socials
+ */
+declare function withRetry<T>(run: (attempt: number) => Promise<T | null>, options?: RetryOptions & {
+    onRetry?: (attempt: number, attempts: number, delayMS: number) => void;
+}): Promise<T | null>;
+
+export { type PollOptions, type RetryOptions, pollUntilReady, withRetry };