@codybrom/denim 1.3.3 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codybrom/denim",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "Typescript/Deno module to simplify posting to Threads",
   "main": "mod.ts",
   "directories": {

package/types.ts

@@ -0,0 +1,235 @@
+// types.ts
+
+/**
+ * Represents the types of media that can be posted on Threads.
+ */
+export type MediaType = "TEXT" | "IMAGE" | "VIDEO" | "CAROUSEL";
+
+/**
+ * Represents the options for controlling who can reply to a post.
+ */
+export type ReplyControl =
+  | "everyone"
+  | "accounts_you_follow"
+  | "mentioned_only";
+
+/**
+ * Represents a request to post content on Threads.
+ */
+export interface ThreadsPostRequest {
+  /** The user ID of the Threads account */
+  userId: string;
+  /** The access token for authentication */
+  accessToken: string;
+  /** The type of media being posted */
+  mediaType: MediaType;
+  /** The text content of the post (optional) */
+  text?: string;
+  /** The URL of the image to be posted (optional, for IMAGE type) */
+  imageUrl?: string;
+  /** 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 - requires special API access) */
+  allowlistedCountryCodes?: string[];
+  /** Controls who can reply to the post (optional) */
+  replyControl?: ReplyControl;
+  /** Array of carousel item IDs (required for CAROUSEL type, not applicable for other types) */
+  children?: string[];
+  /** Whether to return the permalink of the post (optional, default: false) */
+  getPermalink?: boolean;
+}
+
+/**
+ * Represents a single Threads media object.
+ */
+export interface ThreadsPost {
+  /** Unique identifier for the media object */
+  id: string;
+  /** Type of product where the media is published (e.g., "THREADS") */
+  media_product_type: string;
+  /** Type of media (e.g., "TEXT", "IMAGE", "VIDEO", "CAROUSEL") */
+  media_type: MediaType;
+  /** URL of the media content (if applicable) */
+  media_url?: string;
+  /** Permanent link to the post */
+  permalink?: string;
+  /** Information about the owner of the post */
+  owner: { id: string };
+  /** Username of the account that created the post */
+  username: string;
+  /** Text content of the post */
+  text?: string;
+  /** Timestamp of when the post was created (ISO 8601 format) */
+  timestamp: string;
+  /** Short code identifier for the media */
+  shortcode: string;
+  /** URL of the thumbnail image (for video posts) */
+  thumbnail_url?: string;
+  /** List of child posts (for carousel posts) */
+  children?: ThreadsPost[];
+  /** Indicates if the post is a quote of another post */
+  is_quote_post: boolean;
+  /** Accessibility text for the image or video */
+  altText?: string;
+  /** URL of the attached link */
+  linkAttachmentUrl?: string;
+  /** Indicates if the post has replies */
+  hasReplies: boolean;
+  /** Indicates if the post is a reply to another post */
+  isReply: boolean;
+  /** Indicates if the reply is owned by the current user */
+  isReplyOwnedByMe: boolean;
+  /** Information about the root post (for replies) */
+  rootPost?: { id: string };
+  /** Information about the post being replied to */
+  repliedTo?: { id: string };
+  /** Visibility status of the post */
+  hideStatus?: "VISIBLE" | "HIDDEN";
+  /** Controls who can reply to the post */
+  replyAudience?: ReplyControl;
+}
+
+/**
+ * Represents the response structure when retrieving a list of Threads.
+ */
+export interface ThreadsListResponse {
+  /** Array of ThreadsPost representing the retrieved posts */
+  data: ThreadsPost[];
+  /** Pagination information */
+  paging?: {
+    /** Cursors for navigating through pages of results */
+    cursors: {
+      /** Cursor for the previous page */
+      before: string;
+      /** Cursor for the next page */
+      after: string;
+    };
+  };
+}
+
+/**
+ * Represents the publishing limit information for a user.
+ */
+export interface PublishingLimit {
+  /** Current usage count towards the quota */
+  quota_usage: number;
+  /** Configuration for the publishing limit */
+  config: {
+    /** Total allowed quota */
+    quota_total: number;
+    /** Duration of the quota period in seconds */
+    quota_duration: number;
+  };
+}
+
+/**
+ * Represents a Threads media container.
+ */
+export interface ThreadsContainer {
+  /** Unique identifier for the container */
+  id: string;
+  /** Permanent link to the container */
+  permalink: string;
+  /** Status of the container */
+  status: "FINISHED" | "FAILED";
+  /** Error message if the container failed */
+  errorMessage?: string;
+}
+
+/**
+ * Represents a Threads user profile.
+ */
+export interface ThreadsProfile {
+  /** Unique identifier for the user */
+  id: string;
+  /** Username of the account */
+  username: string;
+  /** Display name of the user */
+  name: string;
+  /** URL of the user's profile picture */
+  threadsProfilePictureUrl: string;
+  /** Biography text of the user */
+  threadsBiography: string;
+}
+
+/**
+ * Represents the mock API for Threads operations.
+ */
+export interface MockThreadsAPI {
+  /**
+   * Creates a Threads media container.
+   * @param request The request object containing post details
+   * @returns A promise that resolves to either a string ID or an object with ID and permalink
+   */
+  createThreadsContainer(
+    request: ThreadsPostRequest
+  ): Promise<string | { id: string; permalink: string }>;
+
+  /**
+   * Publishes a Threads media container.
+   * @param userId The user ID
+   * @param accessToken The access token
+   * @param containerId The ID of the container to publish
+   * @param getPermalink Whether to return the permalink
+   * @returns A promise that resolves to either a string ID or an object with ID and permalink
+   */
+  publishThreadsContainer(
+    userId: string,
+    accessToken: string,
+    containerId: string,
+    getPermalink?: boolean
+  ): Promise<string | { id: string; permalink: string }>;
+
+  /**
+   * Creates a carousel item for a Threads post.
+   * @param request The request object containing carousel item details
+   * @returns A promise that resolves to either a string ID or an object with ID
+   */
+  createCarouselItem(
+    request: Omit<ThreadsPostRequest, "mediaType"> & {
+      mediaType: "IMAGE" | "VIDEO";
+    }
+  ): Promise<string | { id: string }>;
+
+  /**
+   * Retrieves the publishing limit for a user.
+   * @param userId The user ID
+   * @param accessToken The access token
+   * @returns A promise that resolves to the publishing limit information
+   */
+  getPublishingLimit(
+    userId: string,
+    accessToken: string
+  ): Promise<PublishingLimit>;
+
+  /**
+   * Retrieves a list of Threads posts for a user.
+   * @param userId The user ID
+   * @param accessToken The access token
+   * @param options Optional parameters for pagination and date range
+   * @returns A promise that resolves to the Threads list response
+   */
+  getThreadsList(
+    userId: string,
+    accessToken: string,
+    options?: {
+      since?: string;
+      until?: string;
+      limit?: number;
+      after?: string;
+      before?: string;
+    }
+  ): Promise<ThreadsListResponse>;
+
+  /**
+   * Retrieves a single Thread post.
+   * @param mediaId The ID of the media to retrieve
+   * @param accessToken The access token
+   * @returns A promise that resolves to the Thread post
+   */
+  getSingleThread(mediaId: string, accessToken: string): Promise<ThreadsPost>;
+}