@addn/sdk 1.0.0

package/src/http/http-client.ts

@@ -0,0 +1,263 @@
+import { AddnClientOptions, HttpRequestOptions } from "./types";
+import { ApiResponse, ValidationErrorDetail } from "../types";
+import {
+  AddnError,
+  AddnNetworkError,
+  AddnTimeoutError,
+  AddnApiError,
+  AddnAuthError,
+  AddnForbiddenError,
+  AddnNotFoundError,
+  AddnConflictError,
+  AddnValidationError,
+  AddnRateLimitError,
+  AddnServerError,
+  AddnUnexpectedError,
+} from "./errors";
+import { TokenManager, TokenPair } from "../auth/token-manager";
+import { LocalStorageAdapter } from "../auth/storage";
+
+export class HttpClient {
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+  public readonly tokenManager: TokenManager;
+  private readonly onRequest?: AddnClientOptions["onRequest"];
+  private readonly onError?: AddnClientOptions["onError"];
+  private readonly onUnauthenticated?: AddnClientOptions["onUnauthenticated"];
+
+  constructor(options: AddnClientOptions) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = options.timeoutMs ?? 30000;
+    this.onRequest = options.onRequest;
+    this.onError = options.onError;
+    this.onUnauthenticated = options.onUnauthenticated;
+
+    const storage = options.storage ?? new LocalStorageAdapter();
+    this.tokenManager = new TokenManager(storage, this.onUnauthenticated);
+  }
+
+  public async request<T = any>(options: HttpRequestOptions): Promise<T> {
+    let opts = { ...options };
+
+    if (this.onRequest) {
+      try {
+        opts = await this.onRequest(opts);
+      } catch (err) {
+        throw new AddnUnexpectedError("Custom onRequest hook failed", err);
+      }
+    }
+
+    try {
+      return await this.executeRequest<T>(opts);
+    } catch (error) {
+      if (error instanceof AddnAuthError && opts.requiresAuth !== false) {
+        // Attempt token refresh
+        const newTokens = await this.tokenManager.handleRefresh(async (refreshToken) => {
+          return await this.rawRefreshTokenCall(refreshToken);
+        });
+
+        if (newTokens) {
+          // Retry request with new token
+          try {
+            return await this.executeRequest<T>(opts);
+          } catch (retryErr) {
+            this.handleErrorTrigger(retryErr);
+            throw retryErr;
+          }
+        }
+      }
+
+      this.handleErrorTrigger(error);
+      throw error;
+    }
+  }
+
+  private async executeRequest<T>(options: HttpRequestOptions): Promise<T> {
+    const method = options.method ?? "GET";
+    const path = options.path.startsWith("/") ? options.path : `/${options.path}`;
+    const url = this.buildUrl(path, options.query);
+
+    const headers: Record<string, string> = { ...options.headers };
+
+    if (options.requiresAuth !== false) {
+      const token = await this.tokenManager.getAccessToken();
+      if (token && !headers["Authorization"]) {
+        headers["Authorization"] = `Bearer ${token}`;
+      }
+    }
+
+    let body: any = undefined;
+    if (options.formData) {
+      body = options.formData;
+    } else if (options.body !== undefined && options.body !== null) {
+      if (!headers["Content-Type"]) {
+        headers["Content-Type"] = "application/json";
+      }
+      body = JSON.stringify(options.body);
+    }
+
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs;
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    // Merge external signal with timeout signal if provided
+    if (options.signal) {
+      options.signal.addEventListener("abort", () => controller.abort());
+    }
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body,
+        signal: controller.signal,
+        credentials: "include",
+      });
+    } catch (err: unknown) {
+      if (
+        (err instanceof Error && err.name === "AbortError") ||
+        (typeof DOMException !== "undefined" && err instanceof DOMException && err.name === "AbortError") ||
+        controller.signal.aborted
+      ) {
+        throw new AddnTimeoutError(timeoutMs);
+      }
+      const msg = err instanceof Error ? err.message : "Network request failed";
+      throw new AddnNetworkError(msg, err);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    return await this.parseResponse<T>(response);
+  }
+
+  private async parseResponse<T>(response: Response): Promise<T> {
+    const contentType = response.headers.get("content-type") || "";
+    let data: any = null;
+    let rawText = "";
+
+    try {
+      if (contentType.includes("application/json")) {
+        data = await response.json();
+      } else {
+        rawText = await response.text();
+        if (rawText) {
+          try {
+            data = JSON.parse(rawText);
+          } catch {
+            data = { message: rawText };
+          }
+        }
+      }
+    } catch (parseErr) {
+      if (!response.ok) {
+        throw new AddnUnexpectedError(`HTTP ${response.status} ${response.statusText} - Failed to parse response body`, parseErr);
+      }
+      return null as unknown as T;
+    }
+
+    if (response.ok) {
+      // Check if response conforms to standard ApiResponse envelope { success: true, data: T }
+      if (data && typeof data === "object" && "data" in data && "success" in data) {
+        return data.data as T;
+      }
+      return data as T;
+    }
+
+    // Handle Error Statuses
+    const message = data?.message || data?.detail || response.statusText || `Request failed with status ${response.status}`;
+    const errorCode = data?.code || "API_ERROR";
+    const statusCode = response.status;
+
+    if (statusCode === 401) {
+      throw new AddnAuthError(message, statusCode, errorCode, data?.details);
+    }
+
+    if (statusCode === 403) {
+      throw new AddnForbiddenError(message, statusCode, errorCode, data?.details);
+    }
+
+    if (statusCode === 404) {
+      throw new AddnNotFoundError(message, statusCode, errorCode, data?.details);
+    }
+
+    if (statusCode === 409) {
+      throw new AddnConflictError(message, statusCode, errorCode, data?.details);
+    }
+
+    if (statusCode === 422) {
+      const details: ValidationErrorDetail[] = Array.isArray(data?.details)
+        ? data.details.map((d: any) => ({
+            field: d.field || d.loc?.join(".") || "payload",
+            message: d.message || d.msg || "Invalid value",
+            type: d.type,
+          }))
+        : [];
+      throw new AddnValidationError(message, details, data);
+    }
+
+    if (statusCode === 429) {
+      const retryHeader = response.headers.get("Retry-After");
+      const retrySecs = retryHeader ? parseInt(retryHeader, 10) : undefined;
+      throw new AddnRateLimitError(message, retrySecs);
+    }
+
+    if (statusCode >= 500) {
+      throw new AddnServerError(message, statusCode, errorCode, data?.details);
+    }
+
+    throw new AddnApiError(message, statusCode, errorCode, data?.details, data);
+  }
+
+  private async rawRefreshTokenCall(refreshToken?: string): Promise<TokenPair> {
+    const url = `${this.baseUrl}/api/v1/auth/refresh`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(refreshToken ? { refresh_token: refreshToken } : {}),
+      credentials: "include",
+    });
+
+    if (!response.ok) {
+      throw new AddnAuthError("Refresh token rejected", response.status);
+    }
+
+    const data = await response.json();
+    const tokenData = data.data || data;
+
+    if (!tokenData.access_token) {
+      throw new AddnAuthError("Refresh endpoint returned invalid token payload");
+    }
+
+    return {
+      accessToken: tokenData.access_token,
+      refreshToken: tokenData.refresh_token,
+    };
+  }
+
+  private buildUrl(path: string, query?: Record<string, string | number | boolean | (string | number)[] | undefined | null>): string {
+    const fullUrl = new URL(`${this.baseUrl}${path}`);
+    if (query) {
+      Object.entries(query).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          if (Array.isArray(value)) {
+            value.forEach((v) => fullUrl.searchParams.append(key, String(v)));
+          } else {
+            fullUrl.searchParams.append(key, String(value));
+          }
+        }
+      });
+    }
+    return fullUrl.toString();
+  }
+
+  private handleErrorTrigger(error: unknown): void {
+    if (this.onError && error instanceof AddnError) {
+      try {
+        this.onError(error);
+      } catch {
+        // Prevent onError callback exceptions from masking original error
+      }
+    }
+  }
+}

package/src/http/types.ts

@@ -0,0 +1,32 @@
+import { AddnError } from "./errors";
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface HttpRequestOptions {
+  path: string;
+  method?: HttpMethod;
+  headers?: Record<string, string>;
+  query?: Record<string, string | number | boolean | (string | number)[] | undefined | null>;
+  body?: unknown;
+  formData?: FormData;
+  requiresAuth?: boolean;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+import { ApiResponse, PaginatedMeta, PaginatedResponse } from "../types";
+
+export interface StorageAdapter {
+  getItem(key: string): string | null | Promise<string | null>;
+  setItem(key: string, value: string): void | Promise<void>;
+  removeItem(key: string): void | Promise<void>;
+}
+
+export interface AddnClientOptions {
+  baseUrl: string;
+  timeoutMs?: number;
+  storage?: StorageAdapter;
+  onUnauthenticated?: () => void;
+  onRequest?: (options: HttpRequestOptions) => HttpRequestOptions | Promise<HttpRequestOptions>;
+  onError?: (error: AddnError) => void;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { AddnClient } from "./client";
+export * from "./http/types";
+export * from "./http/errors";
+export * from "./auth/storage";
+export * from "./auth/token-manager";
+export * from "./modules/auth.module";
+export * from "./modules/orgs.module";
+export * from "./modules/customers.module";
+export * from "./modules/projects.module";
+export * from "./modules/content-plans.module";
+export * from "./modules/scheduling.module";
+export * from "./modules/accounts.module";
+export * from "./modules/analytics.module";
+export * from "./modules/notifications.module";
+export * from "./modules/storage.module";
+export * from "./modules/subscriptions.module";
+export * from "./types";

package/src/modules/accounts.module.ts

@@ -0,0 +1,61 @@
+import { HttpClient } from "../http/http-client";
+import type { ConnectedAccount, ConnectAccountPayload, DevConnectPayload } from "../types";
+
+export class AccountsModule {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  public async listConnectedAccounts(orgId?: string): Promise<ConnectedAccount[]> {
+    const res = await this.http.request<any>({
+      path: "/api/v1/accounts",
+      method: "GET",
+      query: orgId ? { org_id: orgId } : undefined,
+    });
+    if (Array.isArray(res)) return res;
+    if (res?.accounts && Array.isArray(res.accounts)) return res.accounts;
+    return [];
+  }
+
+  public async getConnectUrl(method: "facebook" | "instagram" = "facebook"): Promise<{ url: string }> {
+    return await this.http.request<{ url: string }>({
+      path: `/api/v1/account/connect?login_method=${method}`,
+      method: "POST",
+      body: {},
+    });
+  }
+
+  public async devConnectAccount(payload: DevConnectPayload): Promise<ConnectedAccount> {
+    const res = await this.http.request<any>({
+      path: "/api/v1/account/dev-connect",
+      method: "POST",
+      body: payload,
+    });
+    return res?.account || res;
+  }
+
+  public async connectAccount(payload: ConnectAccountPayload): Promise<ConnectedAccount> {
+    return await this.http.request<ConnectedAccount>({
+      path: "/api/v1/account/connect",
+      method: "POST",
+      body: payload,
+    });
+  }
+
+  public async disconnectAccount(accountId: string): Promise<void> {
+    await this.http.request({
+      path: `/api/v1/account/${accountId}`,
+      method: "DELETE",
+    });
+  }
+
+  public async refreshAccountToken(accountId: string): Promise<any> {
+    return await this.http.request<any>({
+      path: `/api/v1/account/${accountId}/refresh-token`,
+      method: "POST",
+      body: {},
+    });
+  }
+}

package/src/modules/analytics.module.ts

@@ -0,0 +1,26 @@
+import { HttpClient } from "../http/http-client";
+import type { AnalyticsSummary, InstagramAnalyticsData } from "../types";
+
+export class AnalyticsModule {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  public async getSummary(params: { org_id?: string; project_id?: string; start_date?: string; end_date?: string }): Promise<AnalyticsSummary> {
+    return await this.http.request<AnalyticsSummary>({
+      path: "/api/v1/analytics/summary",
+      method: "GET",
+      query: params,
+    });
+  }
+
+  public async getInstagramAnalytics(accountId: string, timeframe: "7d" | "30d" | "90d" = "30d"): Promise<InstagramAnalyticsData> {
+    return await this.http.request<InstagramAnalyticsData>({
+      path: `/api/v1/analytics/instagram/${accountId}`,
+      method: "GET",
+      query: { timeframe },
+    });
+  }
+}

package/src/modules/auth.module.ts

@@ -0,0 +1,129 @@
+import { HttpClient } from "../http/http-client";
+import type {
+  AuthTokenResponse,
+  LoginPayload,
+  RegisterPayload,
+  UserProfile,
+  PasswordResetRequestPayload,
+  PasswordResetConfirmPayload,
+  MetaLoginPayload,
+} from "../types";
+
+export class AuthModule {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  public async login(payload: LoginPayload): Promise<AuthTokenResponse> {
+    const res = await this.http.request<AuthTokenResponse>({
+      path: "/api/v1/auth/login",
+      method: "POST",
+      body: {
+        email: payload.email || payload.username,
+        password: payload.password,
+      },
+      requiresAuth: false,
+    });
+    if (res?.access_token && res?.refresh_token) {
+      await this.http.tokenManager.setTokens(res.access_token, res.refresh_token);
+    }
+    if (res?.user) {
+      await this.http.tokenManager.setUser(res.user);
+    }
+    return res;
+  }
+
+  public async register(payload: RegisterPayload): Promise<AuthTokenResponse> {
+    const res = await this.http.request<AuthTokenResponse>({
+      path: "/api/v1/auth/register",
+      method: "POST",
+      body: payload,
+      requiresAuth: false,
+    });
+    if (res?.access_token && res?.refresh_token) {
+      await this.http.tokenManager.setTokens(res.access_token, res.refresh_token);
+    }
+    if (res?.user) {
+      await this.http.tokenManager.setUser(res.user);
+    }
+    return res;
+  }
+
+  public async getMe(): Promise<UserProfile> {
+    const user = await this.http.request<UserProfile>({
+      path: "/api/v1/auth/me",
+      method: "GET",
+    });
+    if (user) {
+      await this.http.tokenManager.setUser(user);
+    }
+    return user;
+  }
+
+  public async logout(): Promise<void> {
+    try {
+      await this.http.request({
+        path: "/api/v1/auth/logout",
+        method: "POST",
+      });
+    } finally {
+      await this.http.tokenManager.clearTokens();
+    }
+  }
+
+  public async requestPasswordReset(payload: PasswordResetRequestPayload): Promise<void> {
+    await this.http.request({
+      path: "/api/v1/auth/forgot-password",
+      method: "POST",
+      body: payload,
+      requiresAuth: false,
+    });
+  }
+
+  public async confirmPasswordReset(payload: PasswordResetConfirmPayload): Promise<void> {
+    await this.http.request({
+      path: "/api/v1/auth/reset-password",
+      method: "POST",
+      body: payload,
+      requiresAuth: false,
+    });
+  }
+
+  public async completeOnboarding(): Promise<UserProfile> {
+    const user = await this.http.request<UserProfile>({
+      path: "/api/v1/auth/onboarding/complete",
+      method: "PATCH",
+    });
+    if (user) {
+      await this.http.tokenManager.setUser(user);
+    }
+    return user;
+  }
+
+  public async deleteAccount(): Promise<{ message: string }> {
+    const res = await this.http.request<{ message: string }>({
+      path: "/api/v1/auth/account",
+      method: "DELETE",
+    });
+    await this.http.tokenManager.clearTokens();
+    return res;
+  }
+
+  public async metaLogin(payload: MetaLoginPayload): Promise<AuthTokenResponse> {
+    const res = await this.http.request<AuthTokenResponse>({
+      path: "/api/v1/auth/meta/callback",
+      method: "POST",
+      body: payload,
+      requiresAuth: false,
+    });
+    if (res?.access_token && res?.refresh_token) {
+      await this.http.tokenManager.setTokens(res.access_token, res.refresh_token);
+    }
+    if (res?.user) {
+      await this.http.tokenManager.setUser(res.user);
+    }
+    return res;
+  }
+}

package/src/modules/content-plans.module.ts

@@ -0,0 +1,170 @@
+import { HttpClient } from "../http/http-client";
+import type { ContentPlan, CreateContentPlanPayload, UpdateContentPlanPayload } from "../types";
+
+export class ContentPlansModule {
+  private readonly http: HttpClient;
+
+  constructor(http: HttpClient) {
+    this.http = http;
+  }
+
+  public async listContentPlans(params?: {
+    project_id?: string;
+    status?: string;
+    instagram_account_id?: string;
+  }): Promise<ContentPlan[]> {
+    const res = await this.http.request<any>({
+      path: "/api/v1/content-plans",
+      method: "GET",
+      query: params,
+    });
+    if (res && Array.isArray(res.content_plans)) return res.content_plans;
+    if (Array.isArray(res)) return res;
+    return [];
+  }
+
+  public async getContentPlan(planId: string): Promise<ContentPlan> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}`,
+      method: "GET",
+    });
+    return res?.content_plan || res;
+  }
+
+  public async createContentPlan(payload: CreateContentPlanPayload): Promise<ContentPlan> {
+    const res = await this.http.request<any>({
+      path: "/api/v1/content-plans",
+      method: "POST",
+      body: payload,
+    });
+    return res?.content_plan || res;
+  }
+
+  public async updateContentPlan(planId: string, payload: UpdateContentPlanPayload): Promise<ContentPlan> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}`,
+      method: "PATCH",
+      body: payload,
+    });
+    return res?.content_plan || res;
+  }
+
+  public async deleteContentPlan(planId: string): Promise<void> {
+    await this.http.request({
+      path: `/api/v1/content-plans/${planId}`,
+      method: "DELETE",
+    });
+  }
+
+  public async submitForReview(planId: string, approverIds: string[], note?: string): Promise<ContentPlan> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}/submit`,
+      method: "POST",
+      body: { approver_ids: approverIds, note },
+    });
+    return res?.content_plan || res;
+  }
+
+  public async approveDirectly(planId: string, note?: string): Promise<ContentPlan> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}/approve-directly`,
+      method: "POST",
+      body: { note },
+    });
+    return res?.content_plan || res;
+  }
+
+  public async review(planId: string, action: "approved" | "changes_requested", note?: string): Promise<ContentPlan> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}/review`,
+      method: "POST",
+      body: { action, note },
+    });
+    return res?.content_plan || res;
+  }
+
+  public async generateContent(
+    planId: string,
+    outputType: "idea" | "script" | "caption" | "hashtags" | "visual_direction",
+    instructions?: string
+  ): Promise<{ output_type: string; content: string }> {
+    return await this.http.request<{ output_type: string; content: string }>({
+      path: `/api/v1/content-plans/${planId}/generate`,
+      method: "POST",
+      body: { output_type: outputType, instructions },
+    });
+  }
+
+  public async generateStandalone(payload: {
+    output_type: string;
+    instructions: string;
+    title?: string;
+    objective?: string;
+    core_idea?: string;
+    format?: string;
+  }): Promise<{ output_type: string; content: string }> {
+    return await this.http.request<{ output_type: string; content: string }>({
+      path: "/api/v1/content-plans/generate-ai-field",
+      method: "POST",
+      body: payload,
+    });
+  }
+
+  public async generateFullPlan(payload: {
+    content_type: string;
+    prompt: string;
+    project_id?: string;
+  }): Promise<{
+    plan: {
+      title?: string;
+      objective?: string;
+      core_idea?: string;
+      hook?: string;
+      script?: string;
+      call_to_action?: string;
+      visual_direction?: string;
+      caption?: string;
+      hashtags?: string;
+      content_pillar?: string;
+    };
+  }> {
+    return await this.http.request<any>({
+      path: "/api/v1/content-plans/generate-full-plan",
+      method: "POST",
+      body: payload,
+    });
+  }
+
+  public async sharePlan(planId: string, message?: string): Promise<{ recipient_count: number }> {
+    return await this.http.request<{ recipient_count: number }>({
+      path: `/api/v1/content-plans/${planId}/share`,
+      method: "POST",
+      body: { message },
+    });
+  }
+
+  public async getComments(planId: string): Promise<any[]> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}/comments`,
+      method: "GET",
+    });
+    return res?.comments || [];
+  }
+
+  public async addComment(planId: string, body: string): Promise<any> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}/comments`,
+      method: "POST",
+      body: { body },
+    });
+    return res?.comment || res;
+  }
+
+  public async getAudit(planId: string): Promise<any[]> {
+    const res = await this.http.request<any>({
+      path: `/api/v1/content-plans/${planId}/audit`,
+      method: "GET",
+    });
+    return res?.events || [];
+  }
+}