@pindownai/client-js 1.3.3 → 1.3.5

package/dist/PindownClient-Blc0tgqw.d.ts

@@ -0,0 +1,668 @@
+/**
+ * Pin types for the v1 Pins API.
+ * Aligned with backend-api/src/lib/pin-types.ts + pin-config-schemas.ts.
+ * Import per-type *PinConfig interfaces for typed CRUD payloads.
+ */
+declare const PRODUCT_PIN_TYPES: readonly ["markdown", "image", "gallery", "table", "charts", "mermaid", "code", "embed", "pdf-viewer", "excel-viewer", "stat-cards", "timeline", "json-viewer", "json-list", "links", "qr-code", "social-handles", "steps", "trace", "plan", "notes", "csv-viewer", "user-story", "chat", "intro", "mastra", "text-media", "business-card", "video", "audio", "file-upload", "kanban-board", "checklist", "comparison", "calendar", "roadmap", "realtime-canvas"];
+declare const ALL_PIN_TYPES: readonly ["markdown", "image", "gallery", "table", "charts", "mermaid", "code", "embed", "pdf-viewer", "excel-viewer", "stat-cards", "timeline", "json-viewer", "json-list", "links", "qr-code", "social-handles", "steps", "trace", "plan", "notes", "csv-viewer", "user-story", "chat", "intro", "mastra", "text-media", "business-card", "video", "audio", "file-upload", "kanban-board", "checklist", "comparison", "calendar", "roadmap", "realtime-canvas"];
+type ProductPinTypeId = (typeof PRODUCT_PIN_TYPES)[number];
+type PinTypeId = (typeof ALL_PIN_TYPES)[number];
+type PinLayout = '1x1' | '1x2' | '2x1' | '2x2' | '3x1' | '3x2' | '3x3' | '4x4';
+type PinDataType = 'markdown' | 'json' | 'text' | 'pin-card';
+/** @deprecated Use PinTypeId */
+type PinCardType = PinTypeId;
+interface StatCardItem {
+    title: string;
+    value: string | number;
+    change?: string;
+    trend?: 'up' | 'down' | 'neutral' | string;
+    icon?: string;
+    [key: string]: unknown;
+}
+interface TableColumn {
+    id: string;
+    name: string;
+    type?: string;
+    [key: string]: unknown;
+}
+interface TableRow {
+    id: string;
+    cells: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface KanbanColumn {
+    id: string;
+    title: string;
+    cards?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+interface ChecklistItem {
+    id: string;
+    name: string;
+    checked?: boolean;
+    [key: string]: unknown;
+}
+interface GalleryImage {
+    url: string;
+    alt?: string;
+    [key: string]: unknown;
+}
+interface LinkItem {
+    title: string;
+    url: string;
+    [key: string]: unknown;
+}
+interface StepItem {
+    title: string;
+    description?: string;
+    [key: string]: unknown;
+}
+interface MarkdownPinConfig {
+    content?: string;
+    collaboration?: {
+        enabled?: boolean;
+    };
+    [key: string]: unknown;
+}
+interface ImagePinConfig {
+    url?: string;
+    altText?: string;
+    fit?: 'cover' | 'contain' | string;
+    [key: string]: unknown;
+}
+interface GalleryPinConfig {
+    images?: GalleryImage[];
+    [key: string]: unknown;
+}
+interface TablePinConfig {
+    columns: TableColumn[];
+    rows?: TableRow[];
+    [key: string]: unknown;
+}
+interface ChartsPinConfig {
+    chartType?: string;
+    data?: Array<Record<string, unknown>>;
+    xAxis?: string;
+    yAxis?: string;
+    [key: string]: unknown;
+}
+interface MermaidPinConfig {
+    diagram?: string;
+    code?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+interface CodePinConfig {
+    code: string;
+    language?: string;
+    filename?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+interface EmbedPinConfig {
+    url?: string;
+    type?: string;
+    [key: string]: unknown;
+}
+interface PdfViewerPinConfig {
+    pdf: {
+        url: string;
+        fileName?: string;
+        title?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface ExcelViewerPinConfig {
+    excel: {
+        url: string;
+        fileName?: string;
+        title?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface StatCardsPinConfig {
+    cards: StatCardItem[];
+    [key: string]: unknown;
+}
+interface TimelinePinConfig {
+    mode?: string;
+    items?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+interface JsonViewerPinConfig {
+    json?: unknown;
+    jsonString?: string;
+    title?: string;
+    [key: string]: unknown;
+}
+interface JsonListPinConfig {
+    json?: unknown[];
+    jsonString?: string;
+    [key: string]: unknown;
+}
+interface LinksPinConfig {
+    links?: LinkItem[];
+    [key: string]: unknown;
+}
+interface QrCodePinConfig {
+    url?: string;
+    label?: string;
+    [key: string]: unknown;
+}
+interface SocialHandleItem {
+    id?: string;
+    platform: string;
+    url: string;
+    label?: string;
+    [key: string]: unknown;
+}
+interface SocialHandlesPinConfig {
+    title?: string;
+    showLabels?: boolean;
+    iconSize?: number;
+    handles?: SocialHandleItem[];
+    [key: string]: unknown;
+}
+interface StepsPinConfig {
+    steps: StepItem[];
+    [key: string]: unknown;
+}
+type TraceSpanStatus = 'completed' | 'running' | 'pending' | 'failed';
+type TraceSpanType = 'system' | 'agent' | 'tool';
+interface TraceSpanItem {
+    id?: string;
+    type?: TraceSpanType;
+    name: string;
+    status: TraceSpanStatus;
+    timestamp?: string;
+    duration?: string;
+    details?: string;
+}
+interface TracePinConfig {
+    title?: string;
+    live?: boolean;
+    spans: TraceSpanItem[];
+    [key: string]: unknown;
+}
+type PlanContentBlock = {
+    type: 'details';
+    title?: string;
+    items: string[];
+} | {
+    type: 'command';
+    command: string;
+    label?: string;
+} | {
+    type: 'code';
+    code: string;
+    language?: string;
+    filename?: string;
+} | {
+    type: 'text';
+    content: string;
+} | {
+    type: 'link';
+    url: string;
+    label?: string;
+} | {
+    type: 'mermaid';
+    diagram: string;
+    title?: string;
+} | {
+    type: 'summary';
+    content: string;
+    title?: string;
+};
+interface PlanTaskItem {
+    id?: string;
+    number?: string;
+    title: string;
+    label?: string;
+    description?: string;
+    blocks?: PlanContentBlock[];
+    [key: string]: unknown;
+}
+interface PlanPhaseItem {
+    id?: string;
+    title: string;
+    status?: 'pending' | 'in-progress' | 'completed';
+    tasks: PlanTaskItem[];
+    [key: string]: unknown;
+}
+interface PlanPinConfig {
+    title?: string;
+    status?: 'draft' | 'in-progress' | 'completed';
+    breadcrumbs?: Array<{
+        label: string;
+    }>;
+    phases: PlanPhaseItem[];
+    [key: string]: unknown;
+}
+interface NoteItem {
+    id?: string;
+    title: string;
+    content?: string;
+    order?: number;
+    createdAt?: number;
+    updatedAt?: number;
+}
+interface NotesPinConfig {
+    notes?: NoteItem[];
+    [key: string]: unknown;
+}
+interface CsvViewerPinConfig {
+    csvText?: string;
+    csvData?: Array<Record<string, unknown>>;
+    fileName?: string;
+    [key: string]: unknown;
+}
+interface UserStoryPinConfig {
+    title?: string;
+    userStory: string;
+    acceptanceCriteria?: string;
+    [key: string]: unknown;
+}
+interface ChatPinConfig {
+    title?: string;
+    placeholder?: string;
+    /** Pin this discussion thread is about (commentary / feedback). */
+    linked_pin_id?: string;
+    /** Cached title for display without fetching the linked pin. */
+    linked_pin_title?: string;
+    [key: string]: unknown;
+}
+interface IntroPinConfig {
+    heading: string;
+    subheading?: string;
+    [key: string]: unknown;
+}
+interface MastraPinConfig {
+    mode?: 'workflow' | 'agent' | string;
+    agentId?: string;
+    workflowId?: string;
+    [key: string]: unknown;
+}
+interface BusinessCardField {
+    id: string;
+    key: string;
+    value: string;
+}
+interface BusinessCardPinConfig {
+    sectionTitle?: string;
+    fields?: BusinessCardField[];
+    imageConfig?: {
+        url?: string;
+        alt?: string;
+        fileId?: string;
+        [key: string]: unknown;
+    };
+    imagePosition?: 'left' | 'right' | string;
+    [key: string]: unknown;
+}
+interface VideoPinConfig {
+    url?: string;
+    fileId?: string;
+    fileName?: string;
+    mimeType?: 'video/mp4' | string;
+    caption?: string;
+    size?: number;
+    [key: string]: unknown;
+}
+interface AudioPinTrack {
+    url: string;
+    fileId?: string;
+    fileName?: string;
+    mimeType?: 'audio/mpeg' | 'audio/wav' | 'audio/x-wav' | string;
+    size?: number;
+    [key: string]: unknown;
+}
+interface AudioPinConfig {
+    url?: string;
+    fileId?: string;
+    fileName?: string;
+    mimeType?: 'audio/mpeg' | 'audio/wav' | 'audio/x-wav' | string;
+    caption?: string;
+    size?: number;
+    tracks?: AudioPinTrack[];
+    [key: string]: unknown;
+}
+interface TextMediaPinConfig {
+    title?: string;
+    text?: string;
+    subtext?: string;
+    textPosition?: 'left' | 'right' | string;
+    mediaType?: 'embed' | 'image' | string;
+    embedConfig?: {
+        type?: string;
+        url?: string;
+        aspectRatio?: string;
+        autoplay?: boolean;
+        [key: string]: unknown;
+    };
+    imageConfig?: {
+        url?: string;
+        alt?: string;
+        fileId?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface FileUploadPinConfig {
+    files?: Array<Record<string, unknown>>;
+    displayMode?: string;
+    [key: string]: unknown;
+}
+interface KanbanBoardPinConfig {
+    columns: KanbanColumn[];
+    [key: string]: unknown;
+}
+interface ChecklistPinConfig {
+    title?: string;
+    items: ChecklistItem[];
+    [key: string]: unknown;
+}
+interface ComparisonSideConfig {
+    label: string;
+    body: string;
+}
+interface ComparisonMatchPair {
+    left: number;
+    right: number;
+}
+interface ComparisonPinConfig {
+    title?: string;
+    left: ComparisonSideConfig;
+    right: ComparisonSideConfig;
+    highlightedLines?: {
+        left?: number[];
+        right?: number[];
+    };
+    matches?: ComparisonMatchPair[];
+    showVsBadge?: boolean;
+    [key: string]: unknown;
+}
+interface CalendarPinConfig {
+    weekStartsOn?: number;
+    events?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+interface RoadmapPinConfig {
+    title?: string;
+    months?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+interface RealtimeCanvasPinConfig {
+    title?: string;
+    description?: string;
+    roomId?: string;
+    [key: string]: unknown;
+}
+interface PinConfigByType {
+    markdown: MarkdownPinConfig;
+    image: ImagePinConfig;
+    gallery: GalleryPinConfig;
+    table: TablePinConfig;
+    charts: ChartsPinConfig;
+    mermaid: MermaidPinConfig;
+    code: CodePinConfig;
+    embed: EmbedPinConfig;
+    'pdf-viewer': PdfViewerPinConfig;
+    'excel-viewer': ExcelViewerPinConfig;
+    'stat-cards': StatCardsPinConfig;
+    timeline: TimelinePinConfig;
+    'json-viewer': JsonViewerPinConfig;
+    'json-list': JsonListPinConfig;
+    links: LinksPinConfig;
+    'qr-code': QrCodePinConfig;
+    'social-handles': SocialHandlesPinConfig;
+    steps: StepsPinConfig;
+    trace: TracePinConfig;
+    plan: PlanPinConfig;
+    notes: NotesPinConfig;
+    'csv-viewer': CsvViewerPinConfig;
+    'user-story': UserStoryPinConfig;
+    chat: ChatPinConfig;
+    intro: IntroPinConfig;
+    mastra: MastraPinConfig;
+    'text-media': TextMediaPinConfig;
+    'business-card': BusinessCardPinConfig;
+    video: VideoPinConfig;
+    audio: AudioPinConfig;
+    'file-upload': FileUploadPinConfig;
+    'kanban-board': KanbanBoardPinConfig;
+    checklist: ChecklistPinConfig;
+    comparison: ComparisonPinConfig;
+    calendar: CalendarPinConfig;
+    roadmap: RoadmapPinConfig;
+    'realtime-canvas': RealtimeCanvasPinConfig;
+}
+interface PinMetadataBase {
+    title: string;
+    tags?: string[];
+    description?: string;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
+}
+type PinMetadata<T extends PinTypeId = PinTypeId> = PinMetadataBase & {
+    pin_type?: T;
+    pin_config?: PinConfigByType[T];
+    pin_layout?: PinLayout;
+};
+interface CreateTypedPinRequest<T extends PinTypeId> {
+    pin_type: T;
+    pin_config: PinConfigByType[T];
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
+    metadata: PinMetadataBase;
+    pending_invites?: Record<string, 'editor' | 'viewer'>;
+    /** @deprecated Inferred from pin_type */
+    data_type?: PinDataType;
+}
+interface CreateNestedPinRequest<T extends PinTypeId> {
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
+    metadata: PinMetadata<T> & PinMetadataBase;
+    pending_invites?: Record<string, 'editor' | 'viewer'>;
+    data_type?: PinDataType;
+}
+type CreatePinRequest<T extends PinTypeId = PinTypeId> = CreateTypedPinRequest<T> | CreateNestedPinRequest<T>;
+interface UpdatePinRequest<T extends PinTypeId = PinTypeId> {
+    pin_type?: T;
+    pin_config?: PinConfigByType[T];
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+    metadata?: Partial<PinMetadata<T>>;
+}
+interface Pin<T extends PinTypeId = PinTypeId> {
+    id: string;
+    owner_id: string;
+    user_id?: string;
+    title?: string;
+    description?: string;
+    data_type: PinDataType;
+    is_public: boolean;
+    allow_edit: boolean;
+    require_sign_in: boolean;
+    allow_comments: boolean;
+    metadata?: PinMetadata<T>;
+    created_at: string | number;
+    updated_at: string | number;
+}
+interface SharePinRequest {
+    is_public?: boolean;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
+}
+interface ListPinsOptions {
+    limit?: number;
+    offset?: number;
+}
+interface CreatePinOptions {
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
+    pending_invites?: Record<string, 'editor' | 'viewer'>;
+}
+/** Flat create input: metadata + pin_config fields (all pin types). */
+type CreatePinHelperInput<T extends PinTypeId> = PinMetadataBase & CreatePinOptions & PinConfigByType[T];
+/** Flat update input: optional metadata + partial pin_config fields. */
+type UpdatePinHelperInput<T extends PinTypeId> = {
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+    title?: string;
+    tags?: string[];
+    description?: string;
+    metadata?: Partial<PinMetadataBase>;
+} & Partial<PinConfigByType[T]>;
+interface CreateMarkdownPinInput extends PinMetadataBase {
+    content: string;
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
+    pending_invites?: Record<string, 'editor' | 'viewer'>;
+}
+interface CreateStatCardsPinInput extends PinMetadataBase {
+    cards: StatCardItem[];
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+}
+interface CreateTablePinInput extends PinMetadataBase {
+    columns: TableColumn[];
+    rows?: TableRow[];
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+}
+interface UpdateTablePinInput extends UpdatePinHelperInput<'table'> {
+}
+interface CreateEmbedPinInput extends PinMetadataBase {
+    url: string;
+    type?: string;
+    pin_layout?: PinLayout;
+    is_public?: boolean;
+}
+
+/**
+ * API types shared by the v1 Pins client
+ */
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    data: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+interface PaginatedResponse<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * Pins API Methods
+ */
+
+declare class PinsMethods {
+    private client;
+    constructor(client: PindownClient);
+    /** Create a pin (typed via CreatePinRequest&lt;T&gt;) */
+    create<T extends PinTypeId>(request: CreatePinRequest<T>): Promise<Pin<T>>;
+    /** Create helper for any pin type via flat typed input. */
+    createPin<T extends PinTypeId>(pinType: T, input: CreatePinHelperInput<T>): Promise<Pin<T>>;
+    get<T extends PinTypeId = PinTypeId>(pinId: string): Promise<Pin<T>>;
+    list(options?: ListPinsOptions): Promise<PaginatedResponse<Pin>>;
+    update<T extends PinTypeId = PinTypeId>(pinId: string, request: UpdatePinRequest<T>): Promise<Pin<T>>;
+    /** Update helper for any pin type via flat typed input. */
+    updatePin<T extends PinTypeId>(pinId: string, pinType: T, input: UpdatePinHelperInput<T>): Promise<Pin<T>>;
+    delete(pinId: string): Promise<void>;
+    share(pinId: string, request: SharePinRequest): Promise<Pin>;
+    batchGet(pinIds: string[]): Promise<{
+        found: Pin[];
+        not_found: string[];
+        permission_denied: string[];
+    }>;
+    batchCreate(pins: CreatePinRequest[]): Promise<{
+        created: Array<{
+            id: string;
+            index: number;
+            created_at: number;
+        }>;
+        failed: Array<{
+            index: number;
+            error: string;
+        }>;
+    }>;
+    batchUpdate(updates: Array<{
+        id: string;
+    } & UpdatePinRequest>): Promise<{
+        updated: string[];
+        failed: Array<{
+            id: string;
+            error: string;
+        }>;
+        updated_at: number;
+    }>;
+    batchDelete(pinIds: string[]): Promise<{
+        deleted: string[];
+        failed: Array<{
+            id: string;
+            error: string;
+        }>;
+    }>;
+    /** Create a markdown pin with pin_config.content (seeds Yjs on the server). */
+    createMarkdown(input: CreateMarkdownPinInput): Promise<Pin<'markdown'>>;
+    createStatCards(input: CreateStatCardsPinInput): Promise<Pin<'stat-cards'>>;
+    createTable(input: CreateTablePinInput): Promise<Pin<'table'>>;
+    /** Partial table pin_config update with typed columns/rows. */
+    updateTable(pinId: string, input: UpdateTablePinInput): Promise<Pin<'table'>>;
+    createEmbed(input: CreateEmbedPinInput): Promise<Pin<'embed'>>;
+    /**
+     * @deprecated Use createMarkdown({ title, content, ... }) — old signature ignored content in title
+     */
+    createMarkdownLegacy(title: string, additionalMetadata?: Record<string, unknown>): Promise<Pin<'markdown'>>;
+}
+
+/**
+ * Configuration for the v1 Pins API client
+ */
+interface PindownConfig {
+    /** Workspace-plan API key from https://pindown.ai/api-keys */
+    apiKey: string;
+    /** @default 'https://api.pindown.ai/v1' */
+    baseURL?: string;
+    /** @default 3 */
+    maxRetries?: number;
+    /** @default 30000 */
+    timeout?: number;
+}
+
+/**
+ * Pindown API Client — v1 Pins API only
+ */
+
+declare class PindownClient {
+    private config;
+    private readonly rateLimiter;
+    readonly pins: PinsMethods;
+    constructor(config: PindownConfig);
+    request<T = unknown>(method: string, endpoint: string, data?: unknown): Promise<T>;
+    private handleErrorResponse;
+}
+
+export { type TextMediaPinConfig as $, type ApiResponse as A, type MermaidPinConfig as B, type CreatePinHelperInput as C, type PdfViewerPinConfig as D, type EmbedPinConfig as E, type ExcelViewerPinConfig as F, type GalleryImage as G, type StatCardsPinConfig as H, type ImagePinConfig as I, type TimelinePinConfig as J, type KanbanColumn as K, type ListPinsOptions as L, type MarkdownPinConfig as M, type JsonViewerPinConfig as N, type JsonListPinConfig as O, type PinTypeId as P, type LinksPinConfig as Q, type QrCodePinConfig as R, type SharePinRequest as S, type TableColumn as T, type UpdatePinHelperInput as U, type StepsPinConfig as V, type CsvViewerPinConfig as W, type UserStoryPinConfig as X, type ChatPinConfig as Y, type IntroPinConfig as Z, type MastraPinConfig as _, type Pin as a, type BusinessCardField as a0, type BusinessCardPinConfig as a1, type VideoPinConfig as a2, type AudioPinConfig as a3, type AudioPinTrack as a4, type FileUploadPinConfig as a5, type KanbanBoardPinConfig as a6, type ChecklistPinConfig as a7, type CalendarPinConfig as a8, type RoadmapPinConfig as a9, type RealtimeCanvasPinConfig as aa, type CreateMarkdownPinInput as ab, type CreateStatCardsPinInput as ac, type CreateTablePinInput as ad, type UpdateTablePinInput as ae, type CreateEmbedPinInput as af, type PinConfigByType as b, type UpdatePinRequest as c, type CreatePinRequest as d, PindownClient as e, type PindownConfig as f, type PaginatedResponse as g, ALL_PIN_TYPES as h, PRODUCT_PIN_TYPES as i, type ProductPinTypeId as j, type PinLayout as k, type PinDataType as l, type PinCardType as m, type PinMetadataBase as n, type PinMetadata as o, type CreateTypedPinRequest as p, type CreateNestedPinRequest as q, type CreatePinOptions as r, type StatCardItem as s, type TableRow as t, type ChecklistItem as u, type LinkItem as v, type StepItem as w, type GalleryPinConfig as x, type TablePinConfig as y, type ChartsPinConfig as z };