naystack 1.8.19 → 1.9.0

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

@@ -71,25 +71,42 @@ var getInstagramContainerStatus = async (token, id) => {
   };
 };
 
-// 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") {
@@ -100,22 +117,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/instagram/setters.d.mts

@@ -1,6 +1,7 @@
 import { GraphError } from '../meta/types.mjs';
 import { InstagramPostInput } from './types.mjs';
 import '../meta/container.mjs';
+import '../utils/poll.mjs';
 
 /**
  * Publishes to Instagram — feed image, reel, story or carousel, chosen from the

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

@@ -1,6 +1,7 @@
 import { GraphError } from '../meta/types.js';
 import { InstagramPostInput } from './types.js';
 import '../meta/container.js';
+import '../utils/poll.js';
 
 /**
  * Publishes to Instagram — feed image, reel, story or carousel, chosen from the

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

@@ -43,25 +43,42 @@ var getInstagramContainerStatus = async (token, id) => {
   };
 };
 
-// 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") {
@@ -72,22 +89,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/instagram/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';
 
 /**
  * Instagram Messaging API message shape.

package/dist/socials/instagram/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';
 
 /**
  * Instagram Messaging API message shape.

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

@@ -23,24 +23,43 @@ __export(container_exports, {
   createPublisher: () => createPublisher
 });
 module.exports = __toCommonJS(container_exports);
+
+// 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") {
@@ -51,22 +70,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/meta/container.d.mts

@@ -1,35 +1,13 @@
 import { GraphParams, ContainerState } from './types.mjs';
+import { PollOptions, RetryOptions } from '../utils/poll.mjs';
 
 /**
- * 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).
+ * Polling settings for a media container. The default timeout matches Meta,
+ * which stops processing after ~5 min.
  *
  * @category Socials
  */
-type WaitForContainerOptions = {
-    intervalMS?: number;
-    timeoutMS?: number;
-};
-/**
- * Retry settings for creating a media container.
- *
- * Meta intermittently rejects a perfectly valid container — most visibly on
- * carousels, where one arbitrary child fails with "Only photo or video can be
- * accepted as media type." and the identical call succeeds moments later. The
- * failure is transient and carries no distinguishing error code, so container
- * creation is simply retried rather than pattern-matched against Meta's copy.
- *
- * @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;
-};
+type WaitForContainerOptions = PollOptions;
 /**
  * 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
@@ -62,4 +40,4 @@ declare function createPublisher(platform: {
     createChildren: (token: string, items: GraphParams[], wait?: WaitForContainerOptions, retry?: RetryOptions) => Promise<string[] | null>;
 };
 
-export { type RetryOptions, type WaitForContainerOptions, createPublisher };
+export { RetryOptions, type WaitForContainerOptions, createPublisher };

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

@@ -1,35 +1,13 @@
 import { GraphParams, ContainerState } from './types.js';
+import { PollOptions, RetryOptions } from '../utils/poll.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).
+ * Polling settings for a media container. The default timeout matches Meta,
+ * which stops processing after ~5 min.
  *
  * @category Socials
  */
-type WaitForContainerOptions = {
-    intervalMS?: number;
-    timeoutMS?: number;
-};
-/**
- * Retry settings for creating a media container.
- *
- * Meta intermittently rejects a perfectly valid container — most visibly on
- * carousels, where one arbitrary child fails with "Only photo or video can be
- * accepted as media type." and the identical call succeeds moments later. The
- * failure is transient and carries no distinguishing error code, so container
- * creation is simply retried rather than pattern-matched against Meta's copy.
- *
- * @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;
-};
+type WaitForContainerOptions = PollOptions;
 /**
  * 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
@@ -62,4 +40,4 @@ declare function createPublisher(platform: {
     createChildren: (token: string, items: GraphParams[], wait?: WaitForContainerOptions, retry?: RetryOptions) => Promise<string[] | null>;
 };
 
-export { type RetryOptions, type WaitForContainerOptions, createPublisher };
+export { RetryOptions, type WaitForContainerOptions, createPublisher };

package/dist/socials/meta/container.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/provider.cjs.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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/provider.ts
+var provider_exports = {};
+module.exports = __toCommonJS(provider_exports);

package/dist/socials/provider.d.mts

@@ -0,0 +1,52 @@
+import { SocialPlatform, SocialTokens, SocialProfile, SocialPost } from './types.mjs';
+
+/**
+ * One platform's implementation of connect, read profile, read content.
+ *
+ * A plain object with no per-instance state — credentials come from the
+ * environment at call time, tokens are arguments — so each platform exports one
+ * ready-made constant. `InstagramProvider` is the reference implementation.
+ *
+ * Capability is method presence: a platform that can't refresh tokens omits
+ * `refresh`, one with no content-listing API omits `fetchMedia`, and callers
+ * narrow with `if (provider.fetchMedia)`. This describes the platform, not a
+ * token — a token missing a scope still fails at runtime with a `null` return.
+ *
+ * @property auth.authorizationURL - `state` comes back on the callback; `redirectURI` must match what the platform has registered.
+ * @property auth.exchangeCode - Trades the callback `code` for tokens. `platformUserId` is `null` on platforms whose token response carries no id (Google); the route then takes it from `fetchProfile`.
+ * @property auth.refresh - Omitted by platforms whose tokens don't expire or can't be refreshed.
+ * @property fetchMedia - Omitted by platforms with no content-listing API.
+ *
+ * @example
+ * ```ts
+ * import { InstagramProvider } from "naystack/socials";
+ *
+ * const profile = await InstagramProvider.fetchProfile(accessToken);
+ * const posts = await InstagramProvider.fetchMedia?.(accessToken, { limit: 12 });
+ * ```
+ *
+ * @category Socials
+ */
+type SocialProvider = {
+    platform: SocialPlatform;
+    auth: {
+        authorizationURL: (input: {
+            state: string;
+            redirectURI: string;
+            scopes?: string[];
+        }) => string;
+        exchangeCode: (input: {
+            code: string;
+            redirectURI: string;
+        }) => Promise<(SocialTokens & {
+            platformUserId: string | null;
+        }) | null>;
+        refresh?: (tokens: SocialTokens) => Promise<SocialTokens | null>;
+    };
+    fetchProfile: (accessToken: string) => Promise<SocialProfile | null>;
+    fetchMedia?: (accessToken: string, options?: {
+        limit?: number;
+    }) => Promise<SocialPost[]>;
+};
+
+export type { SocialProvider };

package/dist/socials/provider.d.ts

@@ -0,0 +1,52 @@
+import { SocialPlatform, SocialTokens, SocialProfile, SocialPost } from './types.js';
+
+/**
+ * One platform's implementation of connect, read profile, read content.
+ *
+ * A plain object with no per-instance state — credentials come from the
+ * environment at call time, tokens are arguments — so each platform exports one
+ * ready-made constant. `InstagramProvider` is the reference implementation.
+ *
+ * Capability is method presence: a platform that can't refresh tokens omits
+ * `refresh`, one with no content-listing API omits `fetchMedia`, and callers
+ * narrow with `if (provider.fetchMedia)`. This describes the platform, not a
+ * token — a token missing a scope still fails at runtime with a `null` return.
+ *
+ * @property auth.authorizationURL - `state` comes back on the callback; `redirectURI` must match what the platform has registered.
+ * @property auth.exchangeCode - Trades the callback `code` for tokens. `platformUserId` is `null` on platforms whose token response carries no id (Google); the route then takes it from `fetchProfile`.
+ * @property auth.refresh - Omitted by platforms whose tokens don't expire or can't be refreshed.
+ * @property fetchMedia - Omitted by platforms with no content-listing API.
+ *
+ * @example
+ * ```ts
+ * import { InstagramProvider } from "naystack/socials";
+ *
+ * const profile = await InstagramProvider.fetchProfile(accessToken);
+ * const posts = await InstagramProvider.fetchMedia?.(accessToken, { limit: 12 });
+ * ```
+ *
+ * @category Socials
+ */
+type SocialProvider = {
+    platform: SocialPlatform;
+    auth: {
+        authorizationURL: (input: {
+            state: string;
+            redirectURI: string;
+            scopes?: string[];
+        }) => string;
+        exchangeCode: (input: {
+            code: string;
+            redirectURI: string;
+        }) => Promise<(SocialTokens & {
+            platformUserId: string | null;
+        }) | null>;
+        refresh?: (tokens: SocialTokens) => Promise<SocialTokens | null>;
+    };
+    fetchProfile: (accessToken: string) => Promise<SocialProfile | null>;
+    fetchMedia?: (accessToken: string, options?: {
+        limit?: number;
+    }) => Promise<SocialPost[]>;
+};
+
+export type { SocialProvider };

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

@@ -1,6 +1,7 @@
 import { GraphError, ContainerState } from '../meta/types.mjs';
 import { ThreadsPost } from './types.mjs';
 import '../meta/container.mjs';
+import '../utils/poll.mjs';
 
 /**
  * Fetches a single Threads post by id.

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

@@ -1,6 +1,7 @@
 import { GraphError, ContainerState } from '../meta/types.js';
 import { ThreadsPost } from './types.js';
 import '../meta/container.js';
+import '../utils/poll.js';
 
 /**
  * Fetches a single Threads post by id.