@medalsocial/sdk 0.1.2 → 1.0.0

package/dist/index.d.ts

@@ -1,48 +1,393 @@
-type AuthOptions = {
-    kind: "basic";
-    clientId: string;
-    clientSecret: string;
-} | {
-    kind: "bearer";
+interface ClientConfig {
+    baseUrl: string;
     token: string;
-};
-interface ClientOptions {
-    baseUrl?: string;
-    auth: AuthOptions;
-    timeoutMs?: number;
-    userAgent?: string;
+    workspaceId?: string;
+    timeout: number;
+    userAgent: string;
 }
-interface LeadItem {
-    name: string;
+/**
+ * Low-level HTTP client used by all resource classes.
+ * Handles authentication, retries, timeout, and error parsing.
+ */
+declare class BaseClient {
+    readonly config: ClientConfig;
+    constructor(config: ClientConfig);
+    get<T>(path: string, params?: Record<string, string | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown): Promise<T>;
+    patch<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string): Promise<T>;
+    private buildUrl;
+    private request;
+}
+
+/** Successful API response wrapper */
+interface ApiResponse<T> {
+    data: T;
+}
+/** Paginated API response */
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        has_more: boolean;
+        next_cursor: string | null;
+    };
+}
+/** API error thrown by the client */
+declare class MedalApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string, message: string, details?: unknown);
+}
+/** Pagination options for list endpoints */
+interface PaginationOptions {
+    limit?: number;
+    cursor?: string;
+}
+
+interface Contact {
+    id: string;
     email: string;
-    company?: string;
-    source?: string;
-    [key: string]: unknown;
+    first_name: string | null;
+    last_name: string | null;
+    phone: string | null;
+    company: string | null;
+    job_title: string | null;
+    address: Record<string, string> | null;
+    status: ContactStatus;
+    email_status: EmailStatus;
+    label_ids: string[];
+    source: string | null;
+    custom_fields: Record<string, unknown> | null;
+    created_at: string | null;
+    updated_at: string | null;
 }
-interface ContactNoteInput {
-    contactId: string;
-    note: string;
-    [key: string]: unknown;
+interface ContactCreateResult {
+    id: string;
 }
-interface NoteInput {
-    name: string;
+interface ContactUpdateResult {
+    success: true;
+}
+interface ContactRemoveResult {
+    success: true;
+}
+interface ContactNoteResult {
+    id: string;
+}
+type ContactStatus = "lead" | "prospect" | "customer" | "churned" | "archived";
+type EmailStatus = "subscribed" | "unsubscribed" | "bounced" | "complained";
+interface CreateContactInput {
     email: string;
-    firstName?: string;
-    lastName?: string;
+    first_name?: string;
+    last_name?: string;
+    phone?: string;
     company?: string;
+    job_title?: string;
+    address?: Record<string, string>;
+    status?: ContactStatus;
+    email_status?: EmailStatus;
+    label_ids?: string[];
+    /** Label names — auto-created if they don't exist in the workspace. */
+    labels?: string[];
+    custom_fields?: Record<string, unknown>;
+    notes?: string | {
+        content: string;
+        attachments?: {
+            url: string;
+            name: string;
+            type?: string;
+            size?: number;
+        }[];
+    };
+}
+interface UpdateContactInput {
+    email?: string;
+    first_name?: string;
+    last_name?: string;
     phone?: string;
-    content?: string;
-    metadata?: Record<string, unknown>;
+    company?: string;
+    job_title?: string;
+    status?: ContactStatus;
+    email_status?: EmailStatus;
+    label_ids?: string[];
+    /** Label names — auto-created if they don't exist in the workspace. */
+    labels?: string[];
+    custom_fields?: Record<string, unknown>;
 }
-interface CookieRecord {
-    cookie: string;
-    duration: string;
-    description: string;
+interface ListContactsOptions extends PaginationOptions {
+    status?: ContactStatus;
+    email_status?: EmailStatus;
+    label_ids?: string[];
+    search?: string;
 }
-interface CookieCategoryConsent {
-    allowed: boolean;
-    cookieRecords?: CookieRecord[];
+interface ImportContactInput {
+    email: string;
+    first_name?: string;
+    last_name?: string;
+    phone?: string;
+    company?: string;
+    job_title?: string;
+    label_ids?: string[];
+    status?: string;
+}
+interface ImportContactsResult {
+    added: number;
+    skipped: number;
+    total: number;
+}
+interface Activity {
+    id: string;
+    type: string;
+    title: string | null;
+    content: string | null;
+    actor_name: string | null;
+    actor_type: string | null;
+    metadata: unknown;
+    created_at: string | null;
+}
+interface AddNoteInput {
+    content: string;
+}
+
+declare class Contacts {
+    private client;
+    constructor(client: BaseClient);
+    /** List contacts with cursor-based pagination and optional filters. */
+    list(options?: ListContactsOptions): Promise<PaginatedResponse<Contact>>;
+    /** Create a new contact. Email must be unique in the workspace. */
+    create(input: CreateContactInput): Promise<ApiResponse<ContactCreateResult>>;
+    /** Get a contact by ID. */
+    get(id: string): Promise<ApiResponse<Contact>>;
+    /** Update one or more fields on a contact. */
+    update(id: string, input: UpdateContactInput): Promise<ApiResponse<ContactUpdateResult>>;
+    /** Permanently delete a contact. */
+    remove(id: string): Promise<ApiResponse<ContactRemoveResult>>;
+    /** Get the activity timeline for a contact. */
+    activities(id: string, options?: PaginationOptions): Promise<PaginatedResponse<Activity>>;
+    /** Add a note to a contact's timeline. */
+    addNote(id: string, input: AddNoteInput): Promise<ApiResponse<ContactNoteResult>>;
+    /** Bulk import contacts (max 500). Duplicates are skipped. */
+    import(contacts: ImportContactInput[]): Promise<ApiResponse<ImportContactsResult>>;
+}
+
+interface Deal {
+    id: string;
+    title: string;
+    description: string | null;
+    value: number | null;
+    currency: string | null;
+    status: DealStatus;
+    brand_name: string | null;
+    brand_website: string | null;
+    contact_id: string | null;
+    contact_name: string | null;
+    contact_email: string | null;
+    start_date: string | null;
+    end_date: string | null;
+    notes: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+interface DealCreateResult {
+    id: string;
 }
+interface DealUpdateResult {
+    success: true;
+}
+interface DealRemoveResult {
+    success: true;
+}
+type DealStatus = "draft" | "open" | "won" | "lost" | "negotiating" | "proposal_sent" | "on_hold" | "churned";
+interface CreateDealInput {
+    title: string;
+    description?: string;
+    value?: number;
+    currency?: string;
+    brand_name?: string;
+    brand_website?: string;
+    contact_id?: string;
+    contact_name?: string;
+    contact_email?: string;
+    start_date?: string;
+    end_date?: string;
+    notes?: string;
+}
+interface UpdateDealInput {
+    title?: string;
+    description?: string;
+    value?: number;
+    currency?: string;
+    status?: DealStatus;
+    brand_name?: string;
+    brand_website?: string;
+    contact_id?: string | null;
+    contact_name?: string;
+    contact_email?: string;
+    start_date?: string;
+    end_date?: string;
+    notes?: string;
+}
+interface ListDealsOptions extends PaginationOptions {
+    status?: DealStatus;
+    search?: string;
+}
+
+declare class Deals {
+    private client;
+    constructor(client: BaseClient);
+    /** List deals with cursor-based pagination and optional filters. */
+    list(options?: ListDealsOptions): Promise<PaginatedResponse<Deal>>;
+    /** Create a new deal. */
+    create(input: CreateDealInput): Promise<ApiResponse<DealCreateResult>>;
+    /** Get a deal by ID. */
+    get(id: string): Promise<ApiResponse<Deal>>;
+    /** Update one or more fields on a deal. Set contact_id to null to unlink. */
+    update(id: string, input: UpdateDealInput): Promise<ApiResponse<DealUpdateResult>>;
+    /** Permanently delete a deal. */
+    remove(id: string): Promise<ApiResponse<DealRemoveResult>>;
+}
+
+interface SendEmailInput {
+    template_slug: string;
+    to: string;
+    name?: string;
+    locale?: string;
+    fallback_locale?: string;
+    variables?: Record<string, string>;
+    contact_id?: string;
+}
+interface EmailSendResult {
+    id: string;
+    status: string;
+}
+interface EmailSend {
+    id: string;
+    status: string;
+    recipient_email: string;
+    recipient_name: string | null;
+    subject: string | null;
+    template_id: string | null;
+    contact_id: string | null;
+    queued_at: string | null;
+    sent_at: string | null;
+    delivered_at: string | null;
+    opened_at: string | null;
+    clicked_at: string | null;
+    error_message: string | null;
+}
+interface BatchSendInput {
+    template_slug: string;
+    default_locale?: string;
+    recipients: {
+        email: string;
+        name?: string;
+        locale?: string;
+        variables?: Record<string, string>;
+    }[];
+}
+interface BatchSendSummary {
+    batch_id: string;
+    total: number;
+    queued: number;
+    failed: number;
+}
+/** @deprecated Use `BatchSendSummary` for `emails.batch()` responses. */
+type BatchSendResult = BatchSendSummary;
+interface EmailTemplate {
+    id: string;
+    name: string;
+    slug: string;
+    type: string | null;
+    subject: string | null;
+    default_locale: string;
+    available_locales: string[];
+    description: string | null;
+    category: string | null;
+    label_ids: string[];
+    is_active: boolean;
+    is_archived: boolean;
+    version: number;
+    created_at: string | null;
+    updated_at: string | null;
+}
+interface EmailTemplateDetail extends EmailTemplate {
+    html_content: string | null;
+    text_content: string | null;
+    preview_text: string | null;
+    from_name: string | null;
+    from_email: string | null;
+    reply_to: string | null;
+    requested_locale: string | null;
+    resolved_locale: string;
+    content_source: string;
+    localizations: {
+        locale: string | null;
+        subject: string | null;
+        html_content: string | null;
+        text_content: string | null;
+        preview_text: string | null;
+    }[];
+}
+interface GetTemplateOptions {
+    locale?: string;
+    fallback_locale?: string;
+}
+
+declare class EmailTemplates {
+    private client;
+    constructor(client: BaseClient);
+    /** List all active email templates in the workspace. */
+    list(): Promise<ApiResponse<EmailTemplate[]>>;
+    /** Get a specific email template by slug, optionally with locale resolution. */
+    get(slug: string, options?: GetTemplateOptions): Promise<ApiResponse<EmailTemplateDetail>>;
+}
+declare class Emails {
+    private client;
+    readonly templates: EmailTemplates;
+    constructor(client: BaseClient);
+    /** Send a transactional email using a template. Returns a queued job ID (HTTP 202). */
+    send(input: SendEmailInput): Promise<ApiResponse<EmailSendResult>>;
+    /** Get the delivery status of a sent email. */
+    get(id: string): Promise<ApiResponse<EmailSend>>;
+    /** Send the same template to multiple recipients (max 100). Returns HTTP 202. */
+    batch(input: BatchSendInput): Promise<ApiResponse<BatchSendSummary>>;
+}
+
+interface GdprExport {
+    id: string;
+    request_type: string;
+    status: "pending" | "in_progress" | "completed" | "failed" | string;
+    submitted_at: string | null;
+    completed_at: string | null;
+    due_date?: string | null;
+    download_url?: string | null;
+    expires_at?: string | null;
+}
+type ConsentType = "marketing_email" | "analytics_tracking" | "third_party_sharing";
+interface RecordConsentInput {
+    email: string;
+    consent_type: ConsentType;
+    granted: boolean;
+    source?: string;
+    ip_address?: string;
+    consent_text?: string;
+    version?: string;
+}
+interface ConsentRecord {
+    id: string;
+    email: string;
+    consent_type: ConsentType;
+    granted: boolean;
+    granted_at: string | null;
+    revoked_at: string | null;
+    source?: string;
+    version?: string;
+}
+interface ConsentResult {
+    id: string;
+}
+/** @deprecated Use `ConsentRecord[]` for `gdpr.getConsent()` responses. */
+type ContactConsents = ConsentRecord[];
 interface CookieConsentInput {
     domain: string;
     consentStatus: "granted" | "denied" | "partial" | string;
@@ -57,52 +402,212 @@ interface CookieConsentInput {
         [key: string]: CookieCategoryConsent | undefined;
     };
 }
-interface EventSignupInput {
-    contact: {
-        name: string;
-        email: string;
-        company?: string;
-    };
-    event: {
-        externalId: string;
-        name: string;
-        description?: string;
-        time: string;
-        location?: string;
-        thumbnail?: string;
-    };
+interface CookieCategoryConsent {
+    allowed: boolean;
+    cookieRecords?: {
+        cookie: string;
+        duration: string;
+        description: string;
+    }[];
 }
-interface ApiResponse<T> {
-    status: number;
-    data: T;
-    headers: Record<string, string>;
+
+declare class Gdpr {
+    private client;
+    constructor(client: BaseClient);
+    /** Request a workspace data export. Runs asynchronously. */
+    requestExport(): Promise<ApiResponse<{
+        request_id: string;
+        status: string;
+    }>>;
+    /** List all workspace export requests. */
+    listExports(): Promise<ApiResponse<GdprExport[]>>;
+    /** Get the status of a specific export. */
+    getExport(id: string): Promise<ApiResponse<GdprExport>>;
+    /** Record a GDPR consent decision for a contact by email. */
+    recordConsent(input: RecordConsentInput): Promise<ApiResponse<ConsentResult>>;
+    /** Get all consent records for a contact by email. */
+    getConsent(email: string): Promise<ApiResponse<ConsentRecord[]>>;
+    /** Record cookie consent from an external site (legacy endpoint). */
+    cookieConsent(input: CookieConsentInput): Promise<{
+        success: boolean;
+        logId?: string;
+    }>;
 }
-interface TransactionalEmailInput {
-    to: string;
+
+interface Post {
+    id: string;
+    type: PostType;
+    title: string | null;
+    content: string;
+    status: string;
+    channel_ids: string[];
+    variant_count: number;
+    published_count: number;
+    failed_count: number;
+    scheduled_at: string | null;
+    published_at: string | null;
+    created_at: string | null;
+    updated_at: string | null;
+}
+type PostType = "social" | "newsletter" | "blog";
+interface PostVariant {
+    id: string;
+    channel_id: string;
+    content: string;
+    status: string;
+    platform: string | null;
+    channel_display_name: string | null;
+    scheduled_at: string | null;
+    published_at: string | null;
+    platform_post_id: string | null;
+    permalink: string | null;
+    error: string | null;
+}
+interface PostDetail extends Post {
+    variants: PostVariant[];
+}
+interface Channel {
+    id: string;
+    platform: string | null;
+    display_name: string | null;
+    platform_username: string | null;
+    state: string;
+    connected_at: string | null;
+}
+interface CreatePostInput {
+    type?: PostType;
+    title?: string;
+    content: string;
+    channel_ids: string[];
+}
+interface UpdatePostInput {
+    title?: string;
+    content?: string;
+}
+interface SchedulePostInput {
+    /** Unix timestamp (ms) or ISO datetime string. */
+    scheduled_at: number | string;
+}
+interface ListPostsOptions extends PaginationOptions {
+    status?: string;
+    type?: PostType;
+}
+interface ScheduleResult {
+    success: boolean;
+    workflow_id: string;
+}
+interface PublishResult {
+    success: boolean;
+    workflow_id: string;
+}
+
+declare class Posts {
+    private client;
+    constructor(client: BaseClient);
+    /** List posts with cursor-based pagination and optional filters. */
+    list(options?: ListPostsOptions): Promise<PaginatedResponse<Post>>;
+    /** Create a new post with content and target channels. */
+    create(input: CreatePostInput): Promise<ApiResponse<{
+        id: string;
+    }>>;
+    /** Get a post by ID, including its per-channel variants. */
+    get(id: string): Promise<ApiResponse<PostDetail>>;
+    /** Update a draft post's title or content. */
+    update(id: string, input: UpdatePostInput): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /** Delete a post. */
+    remove(id: string): Promise<ApiResponse<{
+        success: boolean;
+    }>>;
+    /** Schedule a post for future publication. */
+    schedule(id: string, input: SchedulePostInput): Promise<ApiResponse<ScheduleResult>>;
+    /** Publish a post immediately to all target channels. */
+    publish(id: string): Promise<ApiResponse<PublishResult>>;
+    /** List connected publishing channels for this workspace. */
+    channels(): Promise<ApiResponse<Channel[]>>;
+}
+
+interface Workspace {
+    id: string;
+    name: string;
     slug: string;
-    additionalData?: Record<string, unknown>;
-}
-declare class MedalSocialClient {
-    private readonly baseUrl;
-    private readonly auth;
-    private readonly timeoutMs;
-    private readonly userAgent;
-    constructor(options: ClientOptions);
-    /** Create one or more leads */
-    createLead<T = unknown>(items: LeadItem[]): Promise<ApiResponse<T>>;
-    /** Create a note attached to a contact by id */
-    createContactNote<T = unknown>(input: ContactNoteInput): Promise<ApiResponse<T>>;
-    /** Record a user’s cookie consent preferences */
-    createCookieConsent<T = unknown>(input: CookieConsentInput): Promise<ApiResponse<T>>;
-    /** Create an event signup with contact and event details */
-    createEventSignup<T = unknown>(input: EventSignupInput): Promise<ApiResponse<T>>;
-    /** Create a free-form note for inbound messages */
-    createNote<T = unknown>(input: NoteInput): Promise<ApiResponse<T>>;
-    /** Send a transactional email by template slug */
-    sendTransactionalEmail<T = unknown>(input: TransactionalEmailInput): Promise<ApiResponse<T>>;
-    private post;
-    private fetchWithAuth;
-    private handleResponse;
+    [key: string]: unknown;
+}
+
+declare class Workspaces {
+    private client;
+    constructor(client: BaseClient);
+    /** List workspaces accessible to the current API key or OAuth token. */
+    list(): Promise<ApiResponse<Workspace[]>>;
+}
+
+interface MedalOptions {
+    /** Override the base URL (defaults to https://api.medalsocial.com). */
+    baseUrl?: string;
+    /** Request timeout in ms (default 30000). */
+    timeout?: number;
+    /**
+     * Workspace ID — required for OAuth access tokens, ignored for API keys.
+     * API keys are scoped to a single workspace, so the workspace is inferred.
+     * OAuth tokens can access multiple workspaces, so you must specify which one.
+     */
+    workspaceId?: string;
+}
+/**
+ * Medal Social SDK client.
+ *
+ * Supports both API key and OAuth access token authentication:
+ *
+ * @example API Key (recommended for server-side)
+ * ```ts
+ * import { Medal } from '@medalsocial/sdk';
+ *
+ * // API keys start with medal_ and are scoped to one workspace
+ * const medal = new Medal('medal_xxx');
+ * ```
+ *
+ * @example OAuth Access Token
+ * ```ts
+ * // OAuth tokens require a workspaceId
+ * const medal = new Medal('oauth_access_token', {
+ *   workspaceId: 'workspace_id_here',
+ * });
+ * ```
+ *
+ * @example Full usage
+ * ```ts
+ * const medal = new Medal('medal_xxx');
+ *
+ * // Posts — create, schedule, publish
+ * const { data: post } = await medal.posts.create({
+ *   content: 'Hello world!',
+ *   channel_ids: ['ch_1'],
+ * });
+ * await medal.posts.schedule(post.id, { scheduled_at: '2026-03-15T10:00:00Z' });
+ *
+ * // Emails — send transactional emails
+ * await medal.emails.send({
+ *   template_slug: 'welcome',
+ *   to: 'user@example.com',
+ *   variables: { name: 'John' },
+ * });
+ *
+ * // Contacts, Deals, GDPR, Workspaces
+ * const contacts = await medal.contacts.list({ status: 'lead' });
+ * const { data: deal } = await medal.deals.create({ title: 'Acme', value: 50000 });
+ * await medal.gdpr.recordConsent({ email: 'u@x.com', consent_type: 'marketing_email', granted: true });
+ * const { data: workspaces } = await medal.workspaces.list();
+ * ```
+ */
+declare class Medal {
+    readonly emails: Emails;
+    readonly contacts: Contacts;
+    readonly deals: Deals;
+    readonly gdpr: Gdpr;
+    readonly posts: Posts;
+    readonly workspaces: Workspaces;
+    constructor(token: string, options?: MedalOptions);
 }
 
-export { type ApiResponse, type AuthOptions, type ClientOptions, type ContactNoteInput, type CookieCategoryConsent, type CookieConsentInput, type CookieRecord, type EventSignupInput, type LeadItem, MedalSocialClient, type NoteInput, type TransactionalEmailInput, MedalSocialClient as default };
+export { type Activity, type AddNoteInput, type ApiResponse, BaseClient, type BatchSendInput, type BatchSendResult, type BatchSendSummary, type Channel, type ConsentRecord, type ConsentResult, type ConsentType, type Contact, type ContactConsents, type ContactCreateResult, type ContactNoteResult, type ContactRemoveResult, type ContactStatus, type ContactUpdateResult, Contacts, type CookieCategoryConsent, type CookieConsentInput, type CreateContactInput, type CreateDealInput, type CreatePostInput, type Deal, type DealCreateResult, type DealRemoveResult, type DealStatus, type DealUpdateResult, Deals, type EmailSend, type EmailSendResult, type EmailStatus, type EmailTemplate, type EmailTemplateDetail, Emails, Gdpr, type GdprExport, type GetTemplateOptions, type ImportContactInput, type ImportContactsResult, type ListContactsOptions, type ListDealsOptions, type ListPostsOptions, Medal, MedalApiError, type MedalOptions, type PaginatedResponse, type PaginationOptions, type Post, type PostDetail, type PostType, type PostVariant, Posts, type PublishResult, type RecordConsentInput, type SchedulePostInput, type ScheduleResult, type SendEmailInput, type UpdateContactInput, type UpdateDealInput, type UpdatePostInput, type Workspace, Workspaces, Medal as default };