@codybrom/denim 1.0.2 → 1.2.0

package/.github/workflows/publish.yml

@@ -1,4 +1,5 @@
 name: Publish
+
 on:
   push:
     branches:
@@ -15,5 +16,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Publish package
+      - name: Publish package to JSR
         run: npx jsr publish
+        
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish package to NPM
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "gpt-context-generator.detectedFileExtensions": [
+    "js",
+    "jsx",
+    "ts",
+    "tsx",
+    "mdx",
+    "json",
+    "md"
+  ]
+}

package/deno.json

@@ -1,7 +1,7 @@
 {
     "name": "@codybrom/denim",
-    "version": "1.0.2",
-    "description": "A Deno function that posts to Threads with text, image, or video.",
+    "version": "1.2.0",
+    "description": "A Deno function for posting to Threads.",
     "entry": "./mod.ts",
     "exports": {
         ".": "./mod.ts"

package/examples/edge-function.ts

@@ -4,10 +4,28 @@ import {
   type ThreadsPostRequest,
   createThreadsContainer,
   publishThreadsContainer,
-} from "jsr:@codybrom/denim@^1.0.2";
+  createCarouselItem,
+  checkHealth,
+  getPublishingLimit,
+} from "jsr:@codybrom/denim@^1.1.0";
 
 async function postToThreads(request: ThreadsPostRequest): Promise<string> {
   try {
+    // Check API health before posting
+    const healthStatus = await checkHealth();
+    if (healthStatus.status !== "ok") {
+      throw new Error(`API is not healthy. Status: ${healthStatus.status}`);
+    }
+
+    // Check rate limit
+    const rateLimit = await getPublishingLimit(
+      request.userId,
+      request.accessToken
+    );
+    if (rateLimit.quota_usage >= rateLimit.config.quota_total) {
+      throw new Error("Rate limit exceeded. Please try again later.");
+    }
+
     if (request.mediaType === "VIDEO" && request.videoUrl) {
       delete request.imageUrl;
     }
@@ -30,42 +48,35 @@ async function postToThreads(request: ThreadsPostRequest): Promise<string> {
 }
 
 Deno.serve(async (req: Request) => {
-  // Health check endpoint
-  if (req.method === "GET" && new URL(req.url).pathname === "/health") {
-    return new Response(JSON.stringify({ status: "ok" }), {
-      status: 200,
-      headers: { "Content-Type": "application/json" },
-    });
-  }
+  const url = new URL(req.url);
 
-  if (req.method !== "POST") {
-    return new Response("Method Not Allowed", { status: 405 });
-  }
-
-  // Log incoming request (without sensitive data)
-  console.log(`Received ${req.method} request to ${new URL(req.url).pathname}`);
-
-  try {
-    let body;
+  // Health check endpoint
+  if (req.method === "GET" && url.pathname === "/health") {
     try {
-      body = await req.json();
+      const healthStatus = await checkHealth();
+      return new Response(JSON.stringify(healthStatus), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
     } catch (error) {
       return new Response(
-        JSON.stringify({
-          success: false,
-          error: "Invalid JSON in request body",
-          details: error.message,
-        }),
+        JSON.stringify({ status: "error", message: error.message }),
         {
-          status: 400,
+          status: 500,
           headers: { "Content-Type": "application/json" },
         }
       );
     }
+  }
+
+  // Rate limit check endpoint
+  if (req.method === "GET" && url.pathname === "/rate-limit") {
+    const userId = url.searchParams.get("userId");
+    const accessToken = url.searchParams.get("accessToken");
 
-    if (!body.userId || !body.accessToken || !body.mediaType) {
+    if (!userId || !accessToken) {
       return new Response(
-        JSON.stringify({ success: false, error: "Missing required fields" }),
+        JSON.stringify({ error: "Missing userId or accessToken" }),
         {
           status: 400,
           headers: { "Content-Type": "application/json" },
@@ -73,31 +84,83 @@ Deno.serve(async (req: Request) => {
       );
     }
 
-    const postRequest: ThreadsPostRequest = {
-      userId: body.userId,
-      accessToken: body.accessToken,
-      mediaType: body.mediaType,
-      text: body.text,
-      imageUrl: body.imageUrl,
-      videoUrl: body.videoUrl,
-    };
-
-    const publishedId = await postToThreads(postRequest);
-
-    return new Response(JSON.stringify({ success: true, publishedId }), {
-      status: 200,
-      headers: { "Content-Type": "application/json" },
-    });
-  } catch (error) {
-    console.error("Error processing request:", error);
-    return new Response(
-      JSON.stringify({ success: false, error: error.message }),
-      {
+    try {
+      const rateLimit = await getPublishingLimit(userId, accessToken);
+      return new Response(JSON.stringify(rateLimit), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    } catch (error) {
+      return new Response(JSON.stringify({ error: error.message }), {
         status: 500,
         headers: { "Content-Type": "application/json" },
+      });
+    }
+  }
+
+  // Main posting endpoint
+  if (req.method === "POST" && url.pathname === "/post") {
+    try {
+      const body = await req.json();
+
+      if (!body.userId || !body.accessToken || !body.mediaType) {
+        return new Response(
+          JSON.stringify({ success: false, error: "Missing required fields" }),
+          {
+            status: 400,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
       }
-    );
+
+      const postRequest: ThreadsPostRequest = {
+        userId: body.userId,
+        accessToken: body.accessToken,
+        mediaType: body.mediaType,
+        text: body.text,
+        imageUrl: body.imageUrl,
+        videoUrl: body.videoUrl,
+        altText: body.altText,
+        linkAttachment: body.linkAttachment,
+        allowlistedCountryCodes: body.allowlistedCountryCodes,
+        replyControl: body.replyControl,
+        children: body.children,
+      };
+
+      if (postRequest.mediaType === "CAROUSEL" && body.carouselItems) {
+        postRequest.children = [];
+        for (const item of body.carouselItems) {
+          const itemId = await createCarouselItem({
+            userId: postRequest.userId,
+            accessToken: postRequest.accessToken,
+            mediaType: item.mediaType,
+            imageUrl: item.imageUrl,
+            videoUrl: item.videoUrl,
+            altText: item.altText,
+          });
+          postRequest.children.push(itemId);
+        }
+      }
+
+      const publishedId = await postToThreads(postRequest);
+
+      return new Response(JSON.stringify({ success: true, publishedId }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    } catch (error) {
+      console.error("Error processing request:", error);
+      return new Response(
+        JSON.stringify({ success: false, error: error.message }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
   }
+
+  return new Response("Not Found", { status: 404 });
 });
 
 /*
@@ -105,32 +168,33 @@ Deno.serve(async (req: Request) => {
   
   1. Deploy this file to your serverless platform that supports Deno.
   
-  2. Send POST requests to <YOUR_FUNCTION_URI> with JSON body containing:
-     - YOUR_AUTH_KEY: Your custom authorization key (if used, otherwise remove the header)
-     - userId: Your Threads user ID
-     - accessToken: Your Threads API access token
-     - mediaType: "TEXT", "IMAGE", or "VIDEO"
-     - text: The text content of your post
-     - imageUrl: URL of the image (for IMAGE posts)
-     - videoUrl: URL of the video (for VIDEO posts)
-  
+  2. Send requests to <YOUR_FUNCTION_URI> with the following endpoints:
+     
+     GET /health - Check the API health status
+     GET /rate-limit?userId=YOUR_USER_ID&accessToken=YOUR_ACCESS_TOKEN - Check rate limit
+     POST /post - Create and publish a post (see below for details)
+
   Example curl commands:
   
+  # Check API health
+  curl -X GET <YOUR_FUNCTION_URI>/health
+
+  # Check rate limit
+  curl -X GET "<YOUR_FUNCTION_URI>/rate-limit?userId=YOUR_USER_ID&accessToken=YOUR_ACCESS_TOKEN"
+
   # Post a text-only Thread
-  curl -X POST <YOUR_FUNCTION_URI> \
+  curl -X POST <YOUR_FUNCTION_URI>/post \
     -H "Content-Type: application/json" \
-    -H "Authorization: Bearer YOUR_AUTH_KEY" \
     -d '{
       "userId": "YOUR_USER_ID",
       "accessToken": "YOUR_ACCESS_TOKEN",
       "mediaType": "TEXT",
       "text": "Hello from Denim!"
     }'
-  
+
   # Post an image Thread
-  curl -X POST <YOUR_FUNCTION_URI> \
+  curl -X POST <YOUR_FUNCTION_URI>/post \
     -H "Content-Type: application/json" \
-    -H "Authorization: Bearer YOUR_AUTH_KEY" \
     -d '{
       "userId": "YOUR_USER_ID",
       "accessToken": "YOUR_ACCESS_TOKEN",
@@ -140,9 +204,8 @@ Deno.serve(async (req: Request) => {
     }'
   
   # Post a video Thread
-  curl -X POST <YOUR_FUNCTION_URI> \
+  curl -X POST <YOUR_FUNCTION_URI>/post \
     -H "Content-Type: application/json" \
-    -H "Authorization: Bearer YOUR_AUTH_KEY" \
     -d '{
       "userId": "YOUR_USER_ID",
       "accessToken": "YOUR_ACCESS_TOKEN",
@@ -151,9 +214,31 @@ Deno.serve(async (req: Request) => {
       "videoUrl": "https://example.com/video.mp4"
     }'
   
+  # Post a carousel Thread
+  curl -X POST <YOUR_FUNCTION_URI>/post \
+    -H "Content-Type: application/json" \
+    -d '{
+      "userId": "YOUR_USER_ID",
+      "accessToken": "YOUR_ACCESS_TOKEN",
+      "mediaType": "CAROUSEL",
+      "text": "Check out this carousel!",
+      "carouselItems": [
+        {
+          "mediaType": "IMAGE",
+          "imageUrl": "https://example.com/image1.jpg",
+          "altText": "First image"
+        },
+        {
+          "mediaType": "VIDEO",
+          "videoUrl": "https://example.com/video.mp4",
+          "altText": "A video"
+        }
+      ]
+    }'
+  
   Note: If both videoUrl and imageUrl are provided in a request with mediaType "VIDEO",
   the imageUrl will be ignored, and only the video will be posted.
-  
+
   Security Note: Ensure that your function is deployed with appropriate access controls
   and authentication mechanisms to protect sensitive data like access tokens.
   */

package/mod.ts

@@ -17,13 +17,23 @@ export interface ThreadsPostRequest {
   /** The access token for authentication */
   accessToken: string;
   /** The type of media being posted */
-  mediaType: "TEXT" | "IMAGE" | "VIDEO";
+  mediaType: "TEXT" | "IMAGE" | "VIDEO" | "CAROUSEL";
   /** The text content of the post (optional) */
   text?: string;
-  /** The URL of the image to be posted (optional) */
+  /** The URL of the image to be posted (optional, for IMAGE type) */
   imageUrl?: string;
-  /** The URL of the video to be posted (optional) */
+  /** The URL of the video to be posted (optional, for VIDEO type) */
   videoUrl?: string;
+  /** The accessibility text for the image or video (optional) */
+  altText?: string;
+  /** The URL to be attached as a link to the post (optional, for text posts only) */
+  linkAttachment?: string;
+  /** List of country codes where the post should be visible (optional) */
+  allowlistedCountryCodes?: string[];
+  /** Controls who can reply to the post (optional) */
+  replyControl?: "everyone" | "accounts_you_follow" | "mentioned_only";
+  /** Array of carousel item IDs (required for CAROUSEL type, not applicable for other types) */
+  children?: string[];
 }
 
 /**
@@ -38,8 +48,11 @@ export interface ThreadsPostRequest {
  * const request: ThreadsPostRequest = {
  *   userId: "123456",
  *   accessToken: "your_access_token",
- *   mediaType: "TEXT",
- *   text: "Hello, Threads!"
+ *   mediaType: "CAROUSEL",
+ *   text: "Check out this carousel!",
+ *   children: ["item1", "item2"],
+ *   allowlistedCountryCodes: ["US", "CA"],
+ *   replyControl: "everyone"
  * };
  * const containerId = await createThreadsContainer(request);
  * ```
@@ -47,13 +60,44 @@ export interface ThreadsPostRequest {
 export async function createThreadsContainer(
   request: ThreadsPostRequest
 ): Promise<string> {
+  // Add input validation
+  if (request.mediaType !== "IMAGE" && request.imageUrl) {
+    throw new Error("imageUrl can only be used with IMAGE media type");
+  }
+  if (request.mediaType !== "VIDEO" && request.videoUrl) {
+    throw new Error("videoUrl can only be used with VIDEO media type");
+  }
+  if (request.mediaType !== "TEXT" && request.linkAttachment) {
+    throw new Error("linkAttachment can only be used with TEXT media type");
+  }
+  if (request.mediaType !== "CAROUSEL" && request.children) {
+    throw new Error("children can only be used with CAROUSEL media type");
+  }
+  if (
+    request.mediaType === "CAROUSEL" &&
+    (!request.children || request.children.length < 2)
+  ) {
+    throw new Error("CAROUSEL media type requires at least 2 children");
+  }
+
   const url = `${THREADS_API_BASE_URL}/${request.userId}/threads`;
   const body = new URLSearchParams({
     access_token: request.accessToken,
     media_type: request.mediaType,
     ...(request.text && { text: request.text }),
-    ...(request.imageUrl && { image_url: request.imageUrl }),
-    ...(request.videoUrl && { video_url: request.videoUrl }),
+    ...(request.mediaType === "IMAGE" &&
+      request.imageUrl && { image_url: request.imageUrl }),
+    ...(request.mediaType === "VIDEO" &&
+      request.videoUrl && { video_url: request.videoUrl }),
+    ...(request.altText && { alt_text: request.altText }),
+    ...(request.mediaType === "TEXT" &&
+      request.linkAttachment && { link_attachment: request.linkAttachment }),
+    ...(request.allowlistedCountryCodes && {
+      allowlisted_country_codes: request.allowlistedCountryCodes.join(","),
+    }),
+    ...(request.replyControl && { reply_control: request.replyControl }),
+    ...(request.mediaType === "CAROUSEL" &&
+      request.children && { children: request.children.join(",") }),
   });
 
   console.log(`Sending request to: ${url}`);
@@ -86,6 +130,92 @@ export async function createThreadsContainer(
   }
 }
 
+/**
+ * Creates a carousel item for a Threads carousel post.
+ *
+ * This function sends a request to the Threads API to create a single item
+ * that will be part of a carousel post. It can be used for both image and
+ * video items.
+ *
+ * @param request - The request object containing carousel item details
+ * @param request.userId - The user ID of the Threads account
+ * @param request.accessToken - The access token for authentication
+ * @param request.mediaType - The type of media for this carousel item ('IMAGE' or 'VIDEO')
+ * @param request.imageUrl - The URL of the image (required if mediaType is 'IMAGE')
+ * @param request.videoUrl - The URL of the video (required if mediaType is 'VIDEO')
+ * @param request.altText - Optional accessibility text for the image or video
+ * @returns A Promise that resolves to the carousel item ID
+ * @throws Will throw an error if the API request fails or returns an invalid response
+ *
+ * @example
+ * ```typescript
+ * const itemRequest = {
+ *   userId: "123456",
+ *   accessToken: "your_access_token",
+ *   mediaType: "IMAGE" as const,
+ *   imageUrl: "https://example.com/image.jpg",
+ *   altText: "A beautiful landscape"
+ * };
+ * try {
+ *   const itemId = await createCarouselItem(itemRequest);
+ *   console.log(`Carousel item created with ID: ${itemId}`);
+ * } catch (error) {
+ *   console.error("Failed to create carousel item:", error);
+ * }
+ * ```
+ */
+export async function createCarouselItem(
+  request: Omit<ThreadsPostRequest, "mediaType"> & {
+    mediaType: "IMAGE" | "VIDEO";
+  }
+): Promise<string> {
+  if (request.mediaType !== "IMAGE" && request.mediaType !== "VIDEO") {
+    throw new Error("Carousel items must be either IMAGE or VIDEO type");
+  }
+
+  if (request.mediaType === "IMAGE" && !request.imageUrl) {
+    throw new Error("imageUrl is required for IMAGE type carousel items");
+  }
+
+  if (request.mediaType === "VIDEO" && !request.videoUrl) {
+    throw new Error("videoUrl is required for VIDEO type carousel items");
+  }
+
+  const url = `${THREADS_API_BASE_URL}/${request.userId}/threads`;
+  const body = new URLSearchParams({
+    access_token: request.accessToken,
+    media_type: request.mediaType,
+    is_carousel_item: "true",
+    ...(request.imageUrl && { image_url: request.imageUrl }),
+    ...(request.videoUrl && { video_url: request.videoUrl }),
+    ...(request.altText && { alt_text: request.altText }),
+  });
+
+  const response = await fetch(url, {
+    method: "POST",
+    body: body,
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+  });
+
+  const responseText = await response.text();
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to create carousel item: ${response.statusText}. Details: ${responseText}`
+    );
+  }
+
+  try {
+    const data = JSON.parse(responseText);
+    return data.id;
+  } catch (error) {
+    console.error(`Failed to parse response JSON: ${error}`);
+    throw new Error(`Invalid response from Threads API: ${responseText}`);
+  }
+}
+
 /**
  * Publishes a Threads media container.
  *
@@ -202,3 +332,40 @@ export function serveRequests() {
     }
   });
 }
+
+/**
+ * Retrieves the current publishing rate limit usage for a user.
+ *
+ * @param userId - The user ID of the Threads account
+ * @param accessToken - The access token for authentication
+ * @returns A Promise that resolves to the rate limit usage information
+ */
+export async function getPublishingLimit(
+  userId: string,
+  accessToken: string
+): Promise<{
+  quota_usage: number;
+  config: {
+    quota_total: number;
+    quota_duration: number;
+  };
+}> {
+  const url = `${THREADS_API_BASE_URL}/${userId}/threads_publishing_limit`;
+  const params = new URLSearchParams({
+    access_token: accessToken,
+    fields: "quota_usage,config",
+  });
+
+  const response = await fetch(`${url}?${params}`);
+  const data = await response.json();
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to get publishing limit: ${
+        data.error?.message || response.statusText
+      }`
+    );
+  }
+
+  return data.data[0];
+}

package/mod_test.ts

@@ -6,13 +6,15 @@ import {
 import {
   createThreadsContainer,
   publishThreadsContainer,
+  createCarouselItem,
+  getPublishingLimit,
   type ThreadsPostRequest,
 } from "./mod.ts";
 
 // Mock fetch response
 globalThis.fetch = (
   input: string | URL | Request,
-  _init?: RequestInit
+  init?: RequestInit
 ): Promise<Response> => {
   const url =
     typeof input === "string"
@@ -21,14 +23,37 @@ globalThis.fetch = (
       ? input.toString()
       : input.url;
 
-  if (url.includes("threads_publish")) {
-    return Promise.resolve({
-      ok: true,
-      status: 200,
-      statusText: "OK",
-      text: () => Promise.resolve(JSON.stringify({ id: "published123" })),
-    } as Response);
-  } else if (url.includes("threads")) {
+  const body =
+    init?.body instanceof URLSearchParams ? init.body : new URLSearchParams();
+
+  if (url.includes("threads")) {
+    if (url.includes("threads_publish")) {
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        text: () => Promise.resolve(JSON.stringify({ id: "published123" })),
+      } as Response);
+    }
+
+    if (body.get("is_carousel_item") === "true") {
+      if (body.get("access_token") === "invalid_token") {
+        return Promise.resolve({
+          ok: false,
+          status: 400,
+          statusText: "Bad Request",
+          text: () =>
+            Promise.resolve(JSON.stringify({ error: "Invalid access token" })),
+        } as Response);
+      }
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        text: () => Promise.resolve(JSON.stringify({ id: "item123" })),
+      } as Response);
+    }
+
     return Promise.resolve({
       ok: true,
       status: 200,
@@ -36,6 +61,7 @@ globalThis.fetch = (
       text: () => Promise.resolve(JSON.stringify({ id: "container123" })),
     } as Response);
   }
+
   return Promise.resolve({
     ok: false,
     status: 500,
@@ -44,30 +70,74 @@ globalThis.fetch = (
   } as Response);
 };
 
-Deno.test("createThreadsContainer should return container ID", async () => {
-  const requestData: ThreadsPostRequest = {
-    userId: "12345",
-    accessToken: "token",
-    mediaType: "TEXT",
-    text: "Hello, Threads!",
-  };
+Deno.test(
+  "createThreadsContainer should return container ID for basic text post",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "TEXT",
+      text: "Hello, Threads!",
+    };
 
-  const containerId = await createThreadsContainer(requestData);
-  assertEquals(containerId, "container123");
-});
+    const containerId = await createThreadsContainer(requestData);
+    assertEquals(containerId, "container123");
+  }
+);
 
-Deno.test("publishThreadsContainer should return published ID", async () => {
-  const userId = "12345";
-  const accessToken = "token";
-  const containerId = "container123";
+Deno.test(
+  "createThreadsContainer should return container ID with text post with link attachment, reply control, and allowlisted countries",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "TEXT",
+      text: "Hello, Threads!",
+      linkAttachment: "https://example.com",
+      replyControl: "everyone",
+      allowlistedCountryCodes: ["US", "CA"],
+    };
 
-  const publishedId = await publishThreadsContainer(
-    userId,
-    accessToken,
-    containerId
-  );
-  assertEquals(publishedId, "published123");
-});
+    const containerId = await createThreadsContainer(requestData);
+    assertEquals(containerId, "container123");
+  }
+);
+
+Deno.test(
+  "createThreadsContainer should handle image post with alt text",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "IMAGE",
+      text: "Check out this image!",
+      imageUrl: "https://example.com/image.jpg",
+      altText: "A beautiful sunset",
+    };
+
+    const containerId = await createThreadsContainer(requestData);
+    assertEquals(containerId, "container123");
+  }
+);
+
+Deno.test(
+  "createThreadsContainer should handle video post with all features",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "VIDEO",
+      text: "Watch this video!",
+      videoUrl: "https://example.com/video.mp4",
+      altText: "A tutorial video",
+      replyControl: "mentioned_only",
+      allowlistedCountryCodes: ["US", "GB"],
+    };
+
+    const containerId = await createThreadsContainer(requestData);
+    assertEquals(containerId, "container123");
+  }
+);
 
 Deno.test("createThreadsContainer should throw error on failure", async () => {
   const requestData: ThreadsPostRequest = {
@@ -75,6 +145,7 @@ Deno.test("createThreadsContainer should throw error on failure", async () => {
     accessToken: "token",
     mediaType: "TEXT",
     text: "Hello, Threads!",
+    linkAttachment: "https://example.com",
   };
 
   globalThis.fetch = (): Promise<Response> =>
@@ -93,6 +164,118 @@ Deno.test("createThreadsContainer should throw error on failure", async () => {
     "Failed to create Threads container"
   );
 });
+Deno.test("createCarouselItem should return item ID", async () => {
+  const requestData = {
+    userId: "12345",
+    accessToken: "token",
+    mediaType: "IMAGE" as const,
+    imageUrl: "https://example.com/image.jpg",
+    altText: "Test image",
+  };
+
+  globalThis.fetch = (
+    _input: string | URL | Request,
+    init?: RequestInit
+  ): Promise<Response> => {
+    const body =
+      init?.body instanceof URLSearchParams ? init.body : new URLSearchParams();
+    if (body.get("is_carousel_item") === "true") {
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        text: () => Promise.resolve(JSON.stringify({ id: "item123" })),
+      } as Response);
+    }
+    return Promise.resolve({
+      ok: false,
+      status: 500,
+      statusText: "Internal Server Error",
+      text: () => Promise.resolve("Error"),
+    } as Response);
+  };
+
+  const itemId = await createCarouselItem(requestData);
+  assertEquals(itemId, "item123");
+});
+
+Deno.test("createCarouselItem should handle video items", async () => {
+  const requestData = {
+    userId: "12345",
+    accessToken: "token",
+    mediaType: "VIDEO" as const,
+    videoUrl: "https://example.com/video.mp4",
+    altText: "Test video",
+  };
+
+  globalThis.fetch = (
+    _input: string | URL | Request,
+    init?: RequestInit
+  ): Promise<Response> => {
+    const body =
+      init?.body instanceof URLSearchParams ? init.body : new URLSearchParams();
+    if (body.get("is_carousel_item") === "true") {
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        statusText: "OK",
+        text: () => Promise.resolve(JSON.stringify({ id: "item123" })),
+      } as Response);
+    }
+    return Promise.resolve({
+      ok: false,
+      status: 500,
+      statusText: "Internal Server Error",
+      text: () => Promise.resolve("Error"),
+    } as Response);
+  };
+
+  const itemId = await createCarouselItem(requestData);
+  assertEquals(itemId, "item123");
+});
+
+Deno.test("createThreadsContainer should handle carousel post", async () => {
+  const requestData: ThreadsPostRequest = {
+    userId: "12345",
+    accessToken: "token",
+    mediaType: "CAROUSEL",
+    text: "Check out this carousel!",
+    children: ["item123", "item456"],
+    replyControl: "everyone",
+    allowlistedCountryCodes: ["US", "CA"],
+  };
+
+  const containerId = await createThreadsContainer(requestData);
+  assertEquals(containerId, "container123");
+});
+
+Deno.test("createCarouselItem should throw error on failure", async () => {
+  const requestData = {
+    userId: "12345",
+    accessToken: "invalid_token",
+    mediaType: "IMAGE" as const,
+    imageUrl: "https://example.com/image.jpg",
+  };
+
+  await assertRejects(
+    () => createCarouselItem(requestData),
+    Error,
+    "Failed to create carousel item"
+  );
+});
+
+Deno.test("publishThreadsContainer should return published ID", async () => {
+  const userId = "12345";
+  const accessToken = "token";
+  const containerId = "container123";
+
+  const publishedId = await publishThreadsContainer(
+    userId,
+    accessToken,
+    containerId
+  );
+  assertEquals(publishedId, "published123");
+});
 
 Deno.test("publishThreadsContainer should throw error on failure", async () => {
   const userId = "12345";
@@ -118,3 +301,201 @@ Deno.test("publishThreadsContainer should throw error on failure", async () => {
     "Failed to publish Threads container"
   );
 });
+
+Deno.test(
+  "createThreadsContainer should throw error when imageUrl is provided for non-IMAGE type",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "TEXT",
+      text: "This shouldn't work",
+      imageUrl: "https://example.com/image.jpg",
+    };
+
+    await assertRejects(
+      () => createThreadsContainer(requestData),
+      Error,
+      "imageUrl can only be used with IMAGE media type"
+    );
+  }
+);
+
+Deno.test(
+  "createThreadsContainer should throw error when videoUrl is provided for non-VIDEO type",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "IMAGE",
+      imageUrl: "https://example.com/image.jpg",
+      videoUrl: "https://example.com/video.mp4",
+    };
+
+    await assertRejects(
+      () => createThreadsContainer(requestData),
+      Error,
+      "videoUrl can only be used with VIDEO media type"
+    );
+  }
+);
+
+Deno.test(
+  "createThreadsContainer should throw error when linkAttachment is provided for non-TEXT type",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "IMAGE",
+      imageUrl: "https://example.com/image.jpg",
+      linkAttachment: "https://example.com",
+    };
+
+    await assertRejects(
+      () => createThreadsContainer(requestData),
+      Error,
+      "linkAttachment can only be used with TEXT media type"
+    );
+  }
+);
+
+Deno.test(
+  "createThreadsContainer should throw error when children is provided for non-CAROUSEL type",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "IMAGE",
+      imageUrl: "https://example.com/image.jpg",
+      children: ["item1", "item2"],
+    };
+
+    await assertRejects(
+      async () => {
+        await createThreadsContainer(requestData);
+      },
+      Error,
+      "Failed to create Threads container"
+    );
+  }
+);
+
+Deno.test(
+  "createThreadsContainer should throw error when CAROUSEL type is used without children",
+  async () => {
+    const requestData: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "CAROUSEL",
+      text: "This carousel has no items",
+    };
+
+    await assertRejects(
+      async () => {
+        await createThreadsContainer(requestData);
+      },
+      Error,
+      "Failed to create Threads container"
+    );
+  }
+);
+
+Deno.test(
+  "createThreadsContainer should not throw error when attributes are used correctly",
+  async () => {
+    const textRequest: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "TEXT",
+      text: "This is a text post",
+      linkAttachment: "https://example.com",
+    };
+
+    const imageRequest: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "IMAGE",
+      imageUrl: "https://example.com/image.jpg",
+      altText: "An example image",
+    };
+
+    const videoRequest: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "VIDEO",
+      videoUrl: "https://example.com/video.mp4",
+      altText: "An example video",
+    };
+
+    const carouselRequest: ThreadsPostRequest = {
+      userId: "12345",
+      accessToken: "token",
+      mediaType: "CAROUSEL",
+      text: "A carousel post",
+      children: ["item1", "item2"],
+    };
+
+    const textContainerId = await createThreadsContainer(textRequest);
+    const imageContainerId = await createThreadsContainer(imageRequest);
+    const videoContainerId = await createThreadsContainer(videoRequest);
+    const carouselContainerId = await createThreadsContainer(carouselRequest);
+
+    assertEquals(textContainerId, "container123");
+    assertEquals(imageContainerId, "container123");
+    assertEquals(videoContainerId, "container123");
+    assertEquals(carouselContainerId, "container123");
+  }
+);
+
+Deno.test(
+  "getPublishingLimit should return rate limit information",
+  async () => {
+    const userId = "12345";
+    const accessToken = "valid_token";
+
+    globalThis.fetch = (_input: string | URL | Request): Promise<Response> => {
+      return Promise.resolve({
+        ok: true,
+        status: 200,
+        json: () =>
+          Promise.resolve({
+            data: [
+              {
+                quota_usage: 10,
+                config: {
+                  quota_total: 250,
+                  quota_duration: 86400,
+                },
+              },
+            ],
+          }),
+      } as Response);
+    };
+
+    const result = await getPublishingLimit(userId, accessToken);
+    assertEquals(result.quota_usage, 10);
+    assertEquals(result.config.quota_total, 250);
+    assertEquals(result.config.quota_duration, 86400);
+  }
+);
+
+Deno.test("getPublishingLimit should throw error on failure", async () => {
+  const userId = "12345";
+  const accessToken = "invalid_token";
+
+  globalThis.fetch = (_input: string | URL | Request): Promise<Response> => {
+    return Promise.resolve({
+      ok: false,
+      status: 400,
+      statusText: "Bad Request",
+      json: () =>
+        Promise.resolve({ error: { message: "Invalid access token" } }),
+    } as Response);
+  };
+
+  await assertRejects(
+    () => getPublishingLimit(userId, accessToken),
+    Error,
+    "Failed to get publishing limit"
+  );
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codybrom/denim",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Typescript/Deno module to simplify posting to Threads with text, images, or videos",
   "main": "mod.ts",
   "directories": {

package/readme.md

@@ -6,10 +6,14 @@
 
 ## Features
 
-- Create and publish posts on Threads
-- Support for text-only, image, and video posts
-- Easy-to-use API
-- Deployable as an edge function
+- Create and publish posts on Threads with an easy-use-API
+- Supports text-only, image, video, and carousel posts
+- Add alt text to image and video posts
+- Attach links to text posts
+- Geo-gate content to specific countries
+- Control who can reply to posts
+- Retrieve publishing rate limit information
+- Ready to deploy as an edge function
 
 ## Installation
 
@@ -25,23 +29,24 @@ This will add the latest version of Denim to your project's dependencies.
 
 ## Usage
 
-To import straight from JSR, 
+To import straight from JSR:
 
 ```typescript
-import { ThreadsPostRequest, createThreadsContainer, publishThreadsContainer } from 'jsr:@codybrom/denim@^1.0.2';
+import { ThreadsPostRequest, createThreadsContainer, publishThreadsContainer } from 'jsr:@codybrom/denim@^1.2.0';
 ```
 
-
 ### Basic Usage
 
 ```typescript
-import { createThreadsContainer, publishThreadsContainer, ThreadsPostRequest } from "jsr:@codybrom/denim@^1.0.2";
+import { createThreadsContainer, publishThreadsContainer, ThreadsPostRequest } from "jsr:@codybrom/denim@^1.2.0";
 
 const request: ThreadsPostRequest = {
   userId: "YOUR_USER_ID",
   accessToken: "YOUR_ACCESS_TOKEN",
   mediaType: "TEXT",
-  text: "Hello, Threads!",
+  text: "Check out Denim on GitHub!",
+  linkAttachment: "https://github.com/codybrom/denim",
+  replyControl: "everyone",
 };
 
 // Create a container
@@ -53,6 +58,24 @@ const publishedId = await publishThreadsContainer(request.userId, request.access
 console.log(`Post published with ID: ${publishedId}`);
 ```
 
+#### Retrieving Publishing Rate Limit
+
+```typescript
+import { getPublishingLimit } from "jsr:@codybrom/denim@^1.2.0";
+
+const userId = "YOUR_USER_ID";
+const accessToken = "YOUR_ACCESS_TOKEN";
+
+try {
+  const rateLimit = await getPublishingLimit(userId, accessToken);
+  console.log("Current usage:", rateLimit.quota_usage);
+  console.log("Total quota:", rateLimit.config.quota_total);
+  console.log("Quota duration (seconds):", rateLimit.config.quota_duration);
+} catch (error) {
+  console.error("Failed to retrieve rate limit information:", error);
+}
+```
+
 ### Posting Different Media Types
 
 #### Text-only Post
@@ -66,7 +89,19 @@ const textRequest: ThreadsPostRequest = {
 };
 ```
 
-#### Image Post
+#### Text Post with Link Attachment
+
+```typescript
+const textRequest: ThreadsPostRequest = {
+  userId: "YOUR_USER_ID",
+  accessToken: "YOUR_ACCESS_TOKEN",
+  mediaType: "TEXT",
+  text: "This is a post with an attached link on Threads!",
+  linkAttachment: "https://example.com",
+};
+```
+
+#### Image Post with Alt Text
 
 ```typescript
 const imageRequest: ThreadsPostRequest = {
@@ -75,6 +110,7 @@ const imageRequest: ThreadsPostRequest = {
   mediaType: "IMAGE",
   text: "Check out this image!",
   imageUrl: "https://example.com/image.jpg",
+  altText: "A beautiful sunset over the ocean",
 };
 ```
 
@@ -90,6 +126,60 @@ const videoRequest: ThreadsPostRequest = {
 };
 ```
 
+#### Video Post with Alt Text, Reply Control and Geo-gating
+
+```typescript
+const videoRequest: ThreadsPostRequest = {
+  userId: "YOUR_USER_ID",
+  accessToken: "YOUR_ACCESS_TOKEN",
+  mediaType: "VIDEO",
+  text: "Watch this video!",
+  videoUrl: "https://example.com/video.mp4",
+  altText: "A tutorial on how to make a chocolate cake",
+  allowlistedCountryCodes: ["US", "GB"],
+  replyControl: "mentioned_only",
+};
+```
+
+#### Carousel Post
+
+```typescript
+import { createCarouselItem, createThreadsContainer, publishThreadsContainer, ThreadsPostRequest } from "jsr:@codybrom/denim@^1.0.4";
+
+// First, create carousel items
+const item1Id = await createCarouselItem({
+  userId: "YOUR_USER_ID",
+  accessToken: "YOUR_ACCESS_TOKEN",
+  mediaType: "IMAGE",
+  imageUrl: "https://example.com/image1.jpg",
+  altText: "First image in the carousel",
+});
+
+const item2Id = await createCarouselItem({
+  userId: "YOUR_USER_ID",
+  accessToken: "YOUR_ACCESS_TOKEN",
+  mediaType: "VIDEO",
+  videoUrl: "https://example.com/video.mp4",
+  altText: "Video in the carousel",
+});
+
+// Then, create the carousel post
+const carouselRequest: ThreadsPostRequest = {
+  userId: "YOUR_USER_ID",
+  accessToken: "YOUR_ACCESS_TOKEN",
+  mediaType: "CAROUSEL",
+  text: "Check out this carousel post!",
+  children: [item1Id, item2Id],
+  replyControl: "everyone",
+  allowlistedCountryCodes: ["US", "CA", "MX"],
+};
+
+const containerId = await createThreadsContainer(carouselRequest);
+const publishedId = await publishThreadsContainer(carouselRequest.userId, carouselRequest.accessToken, containerId);
+
+console.log(`Carousel post published with ID: ${publishedId}`);
+```
+
 ## Deploying as an Edge Function
 
 Denim can be easily deployed as an edge function. An example implementation is provided in `examples/edge-function.ts`.