@hasna/connectors 0.0.1

package/connectors/connect-snap/src/api/creatives.ts

@@ -0,0 +1,232 @@
+import type { SnapClient } from './client';
+import type {
+  Creative,
+  CreativeCreateParams,
+  CreativeUpdateParams,
+  CreativeResponse,
+} from '../types';
+
+/**
+ * Snapchat Creatives API
+ * Manage ad creatives (SNAP_AD, APP_INSTALL, WEB_VIEW, etc.)
+ */
+export class CreativesApi {
+  constructor(private readonly client: SnapClient) {}
+
+  /**
+   * List all creatives for an ad account
+   */
+  async list(adAccountId: string): Promise<Creative[]> {
+    const response = await this.client.get<CreativeResponse>(
+      `/adaccounts/${adAccountId}/creatives`
+    );
+    return response.creatives?.map(c => c.creative) || [];
+  }
+
+  /**
+   * Get a specific creative by ID
+   */
+  async get(creativeId: string): Promise<Creative> {
+    const response = await this.client.get<CreativeResponse>(`/creatives/${creativeId}`);
+    const creative = response.creatives?.[0]?.creative;
+    if (!creative) {
+      throw new Error(`Creative ${creativeId} not found`);
+    }
+    return creative;
+  }
+
+  /**
+   * Create a new creative
+   */
+  async create(params: CreativeCreateParams): Promise<Creative> {
+    const response = await this.client.post<CreativeResponse>(
+      `/adaccounts/${params.ad_account_id}/creatives`,
+      {
+        creatives: [params],
+      }
+    );
+    const creative = response.creatives?.[0]?.creative;
+    if (!creative) {
+      throw new Error('Failed to create creative');
+    }
+    return creative;
+  }
+
+  /**
+   * Update a creative
+   */
+  async update(creativeId: string, params: CreativeUpdateParams): Promise<Creative> {
+    const response = await this.client.put<CreativeResponse>(
+      `/creatives/${creativeId}`,
+      {
+        creatives: [{ id: creativeId, ...params }],
+      }
+    );
+    const creative = response.creatives?.[0]?.creative;
+    if (!creative) {
+      throw new Error('Failed to update creative');
+    }
+    return creative;
+  }
+
+  /**
+   * Delete a creative
+   */
+  async delete(creativeId: string): Promise<void> {
+    await this.client.delete(`/creatives/${creativeId}`);
+  }
+
+  /**
+   * Create a Snap Ad creative
+   */
+  async createSnapAd(
+    adAccountId: string,
+    name: string,
+    topSnapMediaId: string,
+    options?: {
+      headline?: string;
+      brandName?: string;
+      callToAction?: string;
+      shareable?: boolean;
+    }
+  ): Promise<Creative> {
+    return this.create({
+      name,
+      ad_account_id: adAccountId,
+      type: 'SNAP_AD',
+      top_snap_media_id: topSnapMediaId,
+      headline: options?.headline,
+      brand_name: options?.brandName,
+      call_to_action: options?.callToAction as Creative['call_to_action'],
+      shareable: options?.shareable,
+    });
+  }
+
+  /**
+   * Create a Web View creative
+   */
+  async createWebView(
+    adAccountId: string,
+    name: string,
+    topSnapMediaId: string,
+    url: string,
+    options?: {
+      headline?: string;
+      brandName?: string;
+      callToAction?: string;
+      allowSnapJavascriptSdk?: boolean;
+    }
+  ): Promise<Creative> {
+    return this.create({
+      name,
+      ad_account_id: adAccountId,
+      type: 'WEB_VIEW',
+      top_snap_media_id: topSnapMediaId,
+      headline: options?.headline,
+      brand_name: options?.brandName,
+      call_to_action: options?.callToAction as Creative['call_to_action'],
+      web_view_properties: {
+        url,
+        allow_snap_javascript_sdk: options?.allowSnapJavascriptSdk,
+      },
+    });
+  }
+
+  /**
+   * Create an App Install creative
+   */
+  async createAppInstall(
+    adAccountId: string,
+    name: string,
+    topSnapMediaId: string,
+    options: {
+      iosAppId?: string;
+      androidAppUrl?: string;
+      appName?: string;
+      iconMediaId?: string;
+      headline?: string;
+      brandName?: string;
+      callToAction?: string;
+    }
+  ): Promise<Creative> {
+    return this.create({
+      name,
+      ad_account_id: adAccountId,
+      type: 'APP_INSTALL',
+      top_snap_media_id: topSnapMediaId,
+      headline: options.headline,
+      brand_name: options.brandName,
+      call_to_action: options.callToAction as Creative['call_to_action'],
+      app_install_properties: {
+        ios_app_id: options.iosAppId,
+        android_app_url: options.androidAppUrl,
+        app_name: options.appName,
+        icon_media_id: options.iconMediaId,
+      },
+    });
+  }
+
+  /**
+   * Create a Deep Link creative
+   */
+  async createDeepLink(
+    adAccountId: string,
+    name: string,
+    topSnapMediaId: string,
+    deepLinkUri: string,
+    options?: {
+      iosAppId?: string;
+      androidAppUrl?: string;
+      appName?: string;
+      iconMediaId?: string;
+      headline?: string;
+      brandName?: string;
+      callToAction?: string;
+    }
+  ): Promise<Creative> {
+    return this.create({
+      name,
+      ad_account_id: adAccountId,
+      type: 'DEEP_LINK',
+      top_snap_media_id: topSnapMediaId,
+      headline: options?.headline,
+      brand_name: options?.brandName,
+      call_to_action: options?.callToAction as Creative['call_to_action'],
+      deep_link_properties: {
+        deep_link_uri: deepLinkUri,
+        ios_app_id: options?.iosAppId,
+        android_app_url: options?.androidAppUrl,
+        app_name: options?.appName,
+        icon_media_id: options?.iconMediaId,
+      },
+    });
+  }
+
+  /**
+   * Create an Ad to Lens creative
+   */
+  async createAdToLens(
+    adAccountId: string,
+    name: string,
+    topSnapMediaId: string,
+    lensMediaId: string,
+    options?: {
+      headline?: string;
+      brandName?: string;
+      callToAction?: string;
+    }
+  ): Promise<Creative> {
+    return this.create({
+      name,
+      ad_account_id: adAccountId,
+      type: 'AD_TO_LENS',
+      top_snap_media_id: topSnapMediaId,
+      headline: options?.headline,
+      brand_name: options?.brandName,
+      call_to_action: options?.callToAction as Creative['call_to_action'],
+      ad_to_lens_properties: {
+        lens_media_id: lensMediaId,
+      },
+    });
+  }
+}

package/connectors/connect-snap/src/api/index.ts

@@ -0,0 +1,124 @@
+import type { SnapConfig } from '../types';
+import { SnapClient } from './client';
+import { OrganizationsApi } from './organizations';
+import { AccountsApi } from './accounts';
+import { CampaignsApi } from './campaigns';
+import { AdSquadsApi } from './adsquads';
+import { AdsApi } from './ads';
+import { CreativesApi } from './creatives';
+import { MediaApi } from './media';
+import { AudiencesApi } from './audiences';
+import { TargetingApi } from './targeting';
+import { StatsApi } from './stats';
+import { PixelsApi } from './pixels';
+import { ConversionsApi } from './conversions';
+import { CatalogsApi } from './catalogs';
+import { LeadsApi } from './leads';
+
+/**
+ * Snapchat Marketing API client
+ * Provides access to all Snapchat Ads API endpoints
+ */
+export class Snap {
+  private readonly client: SnapClient;
+
+  // API modules
+  public readonly organizations: OrganizationsApi;
+  public readonly accounts: AccountsApi;
+  public readonly campaigns: CampaignsApi;
+  public readonly adSquads: AdSquadsApi;
+  public readonly ads: AdsApi;
+  public readonly creatives: CreativesApi;
+  public readonly media: MediaApi;
+  public readonly audiences: AudiencesApi;
+  public readonly targeting: TargetingApi;
+  public readonly stats: StatsApi;
+  public readonly pixels: PixelsApi;
+  public readonly conversions: ConversionsApi;
+  public readonly catalogs: CatalogsApi;
+  public readonly leads: LeadsApi;
+
+  constructor(config: SnapConfig) {
+    this.client = new SnapClient(config);
+    this.organizations = new OrganizationsApi(this.client);
+    this.accounts = new AccountsApi(this.client);
+    this.campaigns = new CampaignsApi(this.client);
+    this.adSquads = new AdSquadsApi(this.client);
+    this.ads = new AdsApi(this.client);
+    this.creatives = new CreativesApi(this.client);
+    this.media = new MediaApi(this.client);
+    this.audiences = new AudiencesApi(this.client);
+    this.targeting = new TargetingApi(this.client);
+    this.stats = new StatsApi(this.client);
+    this.pixels = new PixelsApi(this.client);
+    this.conversions = new ConversionsApi(this.client);
+    this.catalogs = new CatalogsApi(this.client);
+    this.leads = new LeadsApi(this.client);
+  }
+
+  /**
+   * Create a client from environment variables
+   * Looks for SNAP_ACCESS_TOKEN, SNAP_REFRESH_TOKEN, SNAP_CLIENT_ID, SNAP_CLIENT_SECRET
+   */
+  static fromEnv(): Snap {
+    const accessToken = process.env.SNAP_ACCESS_TOKEN;
+    const refreshToken = process.env.SNAP_REFRESH_TOKEN;
+    const clientId = process.env.SNAP_CLIENT_ID;
+    const clientSecret = process.env.SNAP_CLIENT_SECRET;
+
+    if (!accessToken) {
+      throw new Error('SNAP_ACCESS_TOKEN environment variable is required');
+    }
+
+    return new Snap({
+      accessToken,
+      refreshToken,
+      clientId,
+      clientSecret,
+    });
+  }
+
+  /**
+   * Refresh the access token
+   */
+  async refreshToken(): Promise<void> {
+    await this.client.refreshAccessToken();
+  }
+
+  /**
+   * Check if the client can refresh tokens
+   */
+  canRefreshToken(): boolean {
+    return this.client.canRefreshToken();
+  }
+
+  /**
+   * Get a preview of the access token (for debugging)
+   */
+  getAccessTokenPreview(): string {
+    return this.client.getAccessTokenPreview();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): SnapClient {
+    return this.client;
+  }
+}
+
+export { SnapClient, exchangeCodeForTokens, generateAuthUrl } from './client';
+export { OrganizationsApi } from './organizations';
+export { AccountsApi } from './accounts';
+export { CampaignsApi } from './campaigns';
+export { AdSquadsApi } from './adsquads';
+export { AdsApi } from './ads';
+export { CreativesApi } from './creatives';
+export { MediaApi } from './media';
+export { AudiencesApi } from './audiences';
+export { TargetingApi } from './targeting';
+export { StatsApi } from './stats';
+export { PixelsApi } from './pixels';
+export { ConversionsApi } from './conversions';
+export { CatalogsApi } from './catalogs';
+export { LeadsApi } from './leads';

package/connectors/connect-snap/src/api/leads.ts

@@ -0,0 +1,299 @@
+import type { SnapClient } from './client';
+import type {
+  LeadForm,
+  LeadFormField,
+  LeadFormCreateParams,
+  LeadFormUpdateParams,
+  LeadFormResponse,
+  Lead,
+  LeadResponse,
+} from '../types';
+
+/**
+ * Snapchat Leads API
+ * Manage lead generation forms and retrieve leads
+ */
+export class LeadsApi {
+  constructor(private readonly client: SnapClient) {}
+
+  // ============================================
+  // Lead Form Operations
+  // ============================================
+
+  /**
+   * List all lead forms for an ad account
+   */
+  async listForms(adAccountId: string): Promise<LeadForm[]> {
+    const response = await this.client.get<LeadFormResponse>(
+      `/adaccounts/${adAccountId}/lead_forms`
+    );
+    return response.lead_forms?.map(f => f.lead_form) || [];
+  }
+
+  /**
+   * Get a specific lead form by ID
+   */
+  async getForm(leadFormId: string): Promise<LeadForm> {
+    const response = await this.client.get<LeadFormResponse>(`/lead_forms/${leadFormId}`);
+    const form = response.lead_forms?.[0]?.lead_form;
+    if (!form) {
+      throw new Error(`Lead form ${leadFormId} not found`);
+    }
+    return form;
+  }
+
+  /**
+   * Create a new lead form
+   */
+  async createForm(params: LeadFormCreateParams): Promise<LeadForm> {
+    const response = await this.client.post<LeadFormResponse>(
+      `/adaccounts/${params.ad_account_id}/lead_forms`,
+      {
+        lead_forms: [params],
+      }
+    );
+    const form = response.lead_forms?.[0]?.lead_form;
+    if (!form) {
+      throw new Error('Failed to create lead form');
+    }
+    return form;
+  }
+
+  /**
+   * Update a lead form
+   */
+  async updateForm(leadFormId: string, params: LeadFormUpdateParams): Promise<LeadForm> {
+    const response = await this.client.put<LeadFormResponse>(
+      `/lead_forms/${leadFormId}`,
+      {
+        lead_forms: [{ id: leadFormId, ...params }],
+      }
+    );
+    const form = response.lead_forms?.[0]?.lead_form;
+    if (!form) {
+      throw new Error('Failed to update lead form');
+    }
+    return form;
+  }
+
+  /**
+   * Delete a lead form
+   */
+  async deleteForm(leadFormId: string): Promise<void> {
+    await this.client.delete(`/lead_forms/${leadFormId}`);
+  }
+
+  /**
+   * Archive a lead form
+   */
+  async archiveForm(leadFormId: string): Promise<LeadForm> {
+    return this.updateForm(leadFormId, { status: 'ARCHIVED' });
+  }
+
+  /**
+   * Pause a lead form
+   */
+  async pauseForm(leadFormId: string): Promise<LeadForm> {
+    return this.updateForm(leadFormId, { status: 'PAUSED' });
+  }
+
+  /**
+   * Activate a lead form
+   */
+  async activateForm(leadFormId: string): Promise<LeadForm> {
+    return this.updateForm(leadFormId, { status: 'ACTIVE' });
+  }
+
+  // ============================================
+  // Lead Operations
+  // ============================================
+
+  /**
+   * List all leads for a lead form
+   */
+  async listLeads(leadFormId: string, options?: {
+    limit?: number;
+    offset?: number;
+    startTime?: string;
+    endTime?: string;
+  }): Promise<Lead[]> {
+    const response = await this.client.get<LeadResponse>(
+      `/lead_forms/${leadFormId}/leads`,
+      {
+        limit: options?.limit,
+        offset: options?.offset,
+        start_time: options?.startTime,
+        end_time: options?.endTime,
+      }
+    );
+    return response.leads?.map(l => l.lead) || [];
+  }
+
+  /**
+   * Get a specific lead by ID
+   */
+  async getLead(leadId: string): Promise<Lead> {
+    const response = await this.client.get<LeadResponse>(`/leads/${leadId}`);
+    const lead = response.leads?.[0]?.lead;
+    if (!lead) {
+      throw new Error(`Lead ${leadId} not found`);
+    }
+    return lead;
+  }
+
+  /**
+   * List leads for an ad account across all forms
+   */
+  async listLeadsByAccount(adAccountId: string, options?: {
+    limit?: number;
+    startTime?: string;
+    endTime?: string;
+  }): Promise<Lead[]> {
+    const response = await this.client.get<LeadResponse>(
+      `/adaccounts/${adAccountId}/leads`,
+      {
+        limit: options?.limit,
+        start_time: options?.startTime,
+        end_time: options?.endTime,
+      }
+    );
+    return response.leads?.map(l => l.lead) || [];
+  }
+
+  // ============================================
+  // Helper Methods
+  // ============================================
+
+  /**
+   * Create a basic contact info lead form
+   */
+  async createBasicContactForm(
+    adAccountId: string,
+    name: string,
+    privacyPolicyUrl: string,
+    options?: {
+      headline?: string;
+      description?: string;
+      includePhone?: boolean;
+      thankYouMessage?: string;
+      webhookUrl?: string;
+    }
+  ): Promise<LeadForm> {
+    const fields: LeadFormField[] = [
+      { type: 'FULL_NAME', required: true },
+      { type: 'EMAIL', required: true },
+    ];
+
+    if (options?.includePhone) {
+      fields.push({ type: 'PHONE_NUMBER', required: false });
+    }
+
+    return this.createForm({
+      name,
+      ad_account_id: adAccountId,
+      privacy_policy_url: privacyPolicyUrl,
+      headline: options?.headline,
+      description: options?.description,
+      fields,
+      thank_you_headline: options?.thankYouMessage || 'Thank you!',
+      thank_you_description: 'We will be in touch soon.',
+      leads_webhook_url: options?.webhookUrl,
+    });
+  }
+
+  /**
+   * Create a detailed lead form with custom fields
+   */
+  async createDetailedForm(
+    adAccountId: string,
+    name: string,
+    privacyPolicyUrl: string,
+    fieldTypes: ('FULL_NAME' | 'FIRST_NAME' | 'LAST_NAME' | 'EMAIL' | 'PHONE_NUMBER' |
+      'STREET_ADDRESS' | 'CITY' | 'STATE' | 'ZIP_CODE' | 'COUNTRY' | 'DATE_OF_BIRTH' |
+      'GENDER' | 'COMPANY_NAME' | 'JOB_TITLE' | 'WORK_EMAIL' | 'WORK_PHONE_NUMBER')[],
+    options?: {
+      headline?: string;
+      description?: string;
+      thankYouHeadline?: string;
+      thankYouDescription?: string;
+      thankYouUrl?: string;
+      webhookUrl?: string;
+    }
+  ): Promise<LeadForm> {
+    const fields = fieldTypes.map(type => ({
+      type,
+      required: type === 'EMAIL' || type === 'FULL_NAME',
+    }));
+
+    return this.createForm({
+      name,
+      ad_account_id: adAccountId,
+      privacy_policy_url: privacyPolicyUrl,
+      headline: options?.headline,
+      description: options?.description,
+      fields,
+      thank_you_headline: options?.thankYouHeadline,
+      thank_you_description: options?.thankYouDescription,
+      thank_you_url: options?.thankYouUrl,
+      leads_webhook_url: options?.webhookUrl,
+    });
+  }
+
+  /**
+   * Export leads to CSV format
+   */
+  exportLeadsToCSV(leads: Lead[]): string {
+    if (leads.length === 0) {
+      return '';
+    }
+
+    // Get all unique field types
+    const fieldTypes = new Set<string>();
+    for (const lead of leads) {
+      for (const response of lead.responses) {
+        fieldTypes.add(response.field_type);
+      }
+    }
+
+    const headers = ['lead_id', 'created_at', ...Array.from(fieldTypes)];
+    const rows = leads.map(lead => {
+      const row: Record<string, string> = {
+        lead_id: lead.id,
+        created_at: lead.created_at,
+      };
+
+      for (const response of lead.responses) {
+        row[response.field_type] = response.response;
+      }
+
+      return headers.map(h => row[h] || '');
+    });
+
+    return [headers.join(','), ...rows.map(r => r.join(','))].join('\n');
+  }
+
+  /**
+   * Get available field types for lead forms
+   */
+  getAvailableFieldTypes(): string[] {
+    return [
+      'FULL_NAME',
+      'FIRST_NAME',
+      'LAST_NAME',
+      'EMAIL',
+      'PHONE_NUMBER',
+      'STREET_ADDRESS',
+      'CITY',
+      'STATE',
+      'ZIP_CODE',
+      'COUNTRY',
+      'DATE_OF_BIRTH',
+      'GENDER',
+      'COMPANY_NAME',
+      'JOB_TITLE',
+      'WORK_EMAIL',
+      'WORK_PHONE_NUMBER',
+      'CUSTOM',
+    ];
+  }
+}