@pindownai/client-js 1.1.0 → 1.3.1

package/dist/index.d.cts

@@ -1,239 +1,490 @@
 /**
- * API Types for Pindown
+ * 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.
  */
-interface ApiResponse<T = any> {
-    success: boolean;
-    data: T;
-    error?: {
-        code: string;
-        message: string;
-        details?: any;
-    };
+declare const PRODUCT_PIN_TYPES: readonly ["markdown", "image", "gallery", "table", "charts", "mermaid", "embed", "pdf-viewer", "excel-viewer", "stat-cards", "timeline", "json-viewer", "json-list", "links", "qr-code", "steps", "trace", "plan", "notes", "csv-viewer", "user-story", "chat", "intro", "mastra", "text-media", "business-card", "video", "file-upload", "kanban-board", "checklist", "calendar", "roadmap", "realtime-canvas"];
+declare const ALL_PIN_TYPES: readonly ["markdown", "image", "gallery", "table", "charts", "mermaid", "embed", "pdf-viewer", "excel-viewer", "stat-cards", "timeline", "json-viewer", "json-list", "links", "qr-code", "steps", "trace", "plan", "notes", "csv-viewer", "user-story", "chat", "intro", "mastra", "text-media", "business-card", "video", "file-upload", "kanban-board", "checklist", "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 PaginatedResponse<T> {
-    items: T[];
-    total: number;
-    limit: number;
-    offset: number;
+interface TableColumn {
+    id: string;
+    name: string;
+    type?: string;
+    [key: string]: unknown;
 }
-type PinDataType = 'markdown' | 'json' | 'text' | 'pin-card';
-type PinCardType = 'stat-cards' | 'line-chart' | 'flexible-table' | 'embed' | 'markdown' | 'image' | 'score-gauge' | 'indicator-table' | 'alert-action' | 'bottom-detector' | 'long-short-pie';
-interface Pin {
+interface TableRow {
     id: string;
-    user_id: string;
-    owner_id: string;
-    data_type: PinDataType;
-    pin_card_type?: PinCardType;
-    metadata?: {
-        name?: string;
-        tags?: string[];
-        [key: string]: any;
+    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;
     };
-    is_public: boolean;
-    allow_edit: boolean;
-    require_sign_in: boolean;
-    allow_comments: boolean;
-    created_at: string;
-    updated_at: string;
+    [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 {
+    code?: string;
+    diagram?: string;
+    title?: string;
+    [key: string]: unknown;
 }
-interface CreatePinRequest {
-    data_type?: PinDataType;
-    pin_card_type?: PinCardType;
-    is_public?: boolean;
-    metadata: {
-        title: string;
-        tags?: string[];
-        allow_edit?: boolean;
-        require_sign_in?: boolean;
-        allow_comments?: boolean;
-        pin_card_type?: PinCardType;
-        pin_card_layout?: string;
-        pin_card_config?: any;
-        [key: string]: any;
+interface EmbedPinConfig {
+    url?: string;
+    type?: string;
+    [key: string]: unknown;
+}
+interface PdfViewerPinConfig {
+    pdf: {
+        url: string;
+        fileName?: string;
+        title?: string;
+        [key: string]: unknown;
     };
-    pending_invites?: Record<string, 'editor' | 'viewer'>;
+    [key: string]: unknown;
 }
-interface UpdatePinRequest {
-    is_public?: boolean;
-    metadata?: Pin['metadata'];
+interface ExcelViewerPinConfig {
+    excel: {
+        url: string;
+        fileName?: string;
+        title?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
 }
-interface SharePinRequest {
-    is_public?: boolean;
-    allow_edit?: boolean;
-    require_sign_in?: boolean;
-    allow_comments?: boolean;
+interface StatCardsPinConfig {
+    cards: StatCardItem[];
+    [key: string]: unknown;
 }
-interface ListPinsOptions {
-    limit?: number;
-    offset?: number;
+interface TimelinePinConfig {
+    mode?: string;
+    items?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
 }
-interface Pinboard {
-    id: string;
-    user_id: string;
+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 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;
-    tags?: string[];
-    layout?: Record<string, any>;
-    mobile_layout?: Record<string, any>;
-    pins?: Pin[];
-    is_public: boolean;
-    allow_comments: boolean;
-    require_sign_in: boolean;
-    created_at: string;
-    updated_at: string;
+    label?: string;
+    description?: string;
+    blocks?: PlanContentBlock[];
+    [key: string]: unknown;
 }
-interface CreatePinboardRequest {
+interface PlanPhaseItem {
+    id?: string;
     title: string;
-    tags?: string[];
-    layout?: Record<string, any>;
-    mobile_layout?: Record<string, any>;
+    status?: 'pending' | 'in-progress' | 'completed';
+    tasks: PlanTaskItem[];
+    [key: string]: unknown;
 }
-interface UpdatePinboardRequest {
+interface PlanPinConfig {
     title?: string;
-    tags?: string[];
-    is_public?: boolean;
-    allow_comments?: boolean;
-    require_sign_in?: boolean;
+    status?: 'draft' | 'in-progress' | 'completed';
+    breadcrumbs?: Array<{
+        label: string;
+    }>;
+    phases: PlanPhaseItem[];
+    [key: string]: unknown;
 }
-interface AddPinToPinboardRequest {
-    pin_id: string;
-    position?: {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    };
+interface NoteItem {
+    id?: string;
+    title: string;
+    content?: string;
+    order?: number;
+    createdAt?: number;
+    updatedAt?: number;
 }
-interface UpdatePinboardLayoutRequest {
-    layout?: Record<string, any>;
-    mobile_layout?: Record<string, any>;
+interface NotesPinConfig {
+    notes?: NoteItem[];
+    [key: string]: unknown;
 }
-type DatasetType = 'json' | 'markdown';
-interface Dataset {
-    id: string;
-    user_id: string;
-    name: string;
-    type: DatasetType;
-    data: any;
-    created_at: string;
-    updated_at: string;
+interface CsvViewerPinConfig {
+    csvText?: string;
+    csvData?: Array<Record<string, unknown>>;
+    fileName?: string;
+    [key: string]: unknown;
 }
-interface CreateDatasetRequest {
-    name: string;
-    type: DatasetType;
-    data: any;
+interface UserStoryPinConfig {
+    title?: string;
+    userStory: string;
+    acceptanceCriteria?: string;
+    [key: string]: unknown;
+}
+interface ChatPinConfig {
+    title?: string;
+    placeholder?: string;
+    [key: string]: unknown;
+}
+interface IntroPinConfig {
+    heading: string;
+    subheading?: string;
+    [key: string]: unknown;
 }
-interface UpdateDatasetRequest {
-    name?: string;
-    type?: DatasetType;
-    data?: any;
+interface MastraPinConfig {
+    mode?: 'workflow' | 'agent' | string;
+    agentId?: string;
+    workflowId?: string;
+    [key: string]: unknown;
 }
-interface Page {
+interface BusinessCardField {
     id: string;
-    owner_id: string;
-    is_public: boolean;
-    metadata: {
-        title: string;
-        description?: string;
-        tags: string[];
-        created_at: string;
-        updated_at?: string;
+    key: string;
+    value: string;
+}
+interface BusinessCardPinConfig {
+    sectionTitle?: string;
+    fields?: BusinessCardField[];
+    imageConfig?: {
+        url?: string;
+        alt?: string;
+        fileId?: string;
+        [key: string]: unknown;
     };
-    pins: string[];
-    layout?: Record<string, any>;
-    created_at: number;
-    updated_at: number;
-}
-interface CreatePageRequest {
-    metadata: {
-        title: string;
-        description?: string;
-        tags?: string[];
+    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 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;
     };
-    pins?: string[];
-    layout?: Record<string, any>;
-    is_public?: boolean;
-    allow_comments?: boolean;
+    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 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;
+    embed: EmbedPinConfig;
+    'pdf-viewer': PdfViewerPinConfig;
+    'excel-viewer': ExcelViewerPinConfig;
+    'stat-cards': StatCardsPinConfig;
+    timeline: TimelinePinConfig;
+    'json-viewer': JsonViewerPinConfig;
+    'json-list': JsonListPinConfig;
+    links: LinksPinConfig;
+    'qr-code': QrCodePinConfig;
+    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;
+    'file-upload': FileUploadPinConfig;
+    'kanban-board': KanbanBoardPinConfig;
+    checklist: ChecklistPinConfig;
+    calendar: CalendarPinConfig;
+    roadmap: RoadmapPinConfig;
+    'realtime-canvas': RealtimeCanvasPinConfig;
+}
+interface PinMetadataBase {
+    title: string;
+    tags?: string[];
+    description?: string;
+    allow_edit?: boolean;
     require_sign_in?: boolean;
-    include_datasets?: boolean;
+    allow_comments?: boolean;
 }
-interface UpdatePageRequest {
-    metadata?: {
-        title?: string;
-        description?: string;
-        tags?: string[];
-    };
+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;
-    include_datasets?: 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 AddPinToPageRequest {
-    pin_id: string;
+interface SharePinRequest {
+    is_public?: boolean;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
 }
-interface ListPagesOptions {
+interface ListPinsOptions {
     limit?: number;
     offset?: number;
 }
-type BlockType = 'markdown' | 'mermaid' | 'conditional' | 'image' | 'stat-cards' | 'line-chart' | 'flexible-table' | 'embed';
-interface Block {
-    id: string;
-    pin_id?: string;
-    title: string;
-    type: BlockType;
-    template: string | Record<string, any>;
-    order: number;
-    created_at?: string;
-    updated_at?: string;
+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 CreateBlockRequest {
-    title: string;
-    type: BlockType;
-    template: string | Record<string, any>;
-    order?: number;
+interface CreateStatCardsPinInput extends PinMetadataBase {
+    cards: StatCardItem[];
+    pin_layout?: PinLayout;
+    is_public?: boolean;
 }
-interface UpdateBlockRequest {
-    title?: string;
-    type?: BlockType;
-    template?: string | Record<string, any>;
-    order?: number;
+interface CreateTablePinInput extends PinMetadataBase {
+    columns: TableColumn[];
+    rows?: TableRow[];
+    pin_layout?: PinLayout;
+    is_public?: boolean;
 }
-type CollaboratorRole = 'viewer' | 'editor' | 'owner';
-interface Collaborator {
-    user_id: string;
-    email: string;
-    role: CollaboratorRole;
-    added_at: string;
-}
-interface InviteCollaboratorRequest {
-    email: string;
-    role: CollaboratorRole;
-}
-interface UpdateCollaboratorRoleRequest {
-    role: CollaboratorRole;
-}
-interface Permissions {
-    role: CollaboratorRole;
-    can_view: boolean;
-    can_edit: boolean;
-    can_delete: boolean;
-    can_share: boolean;
-    can_manage_collaborators: boolean;
-}
-interface RateLimitInfo {
-    tier: string;
-    minute: {
-        limit: number;
-        used: number;
-        remaining: number;
-        resetAt: Date;
-    };
-    hour: {
-        limit: number;
-        used: number;
-        remaining: number;
-        resetAt: Date;
+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
@@ -242,41 +493,18 @@ interface RateLimitInfo {
 declare class PinsMethods {
     private client;
     constructor(client: PindownClient);
-    /**
-     * Create a new pin
-     */
-    create(request: CreatePinRequest): Promise<Pin>;
-    /**
-     * Get a pin by ID
-     */
-    get(pinId: string): Promise<Pin>;
-    /**
-     * List all pins
-     */
+    /** Create a pin (typed via CreatePinRequest&lt;T&gt;) */
+    create<T extends PinTypeId>(request: CreatePinRequest<T>): Promise<Pin<T>>;
+    get<T extends PinTypeId = PinTypeId>(pinId: string): Promise<Pin<T>>;
     list(options?: ListPinsOptions): Promise<PaginatedResponse<Pin>>;
-    /**
-     * Update a pin
-     */
-    update(pinId: string, request: UpdatePinRequest): Promise<Pin>;
-    /**
-     * Delete a pin
-     */
+    update<T extends PinTypeId = PinTypeId>(pinId: string, request: UpdatePinRequest<T>): Promise<Pin<T>>;
     delete(pinId: string): Promise<void>;
-    /**
-     * Update pin sharing settings
-     */
     share(pinId: string, request: SharePinRequest): Promise<Pin>;
-    /**
-     * Get multiple pins by IDs in a single request (max 100 pins)
-     */
     batchGet(pinIds: string[]): Promise<{
         found: Pin[];
         not_found: string[];
         permission_denied: string[];
     }>;
-    /**
-     * Create multiple pins in a single request (max 50 pins)
-     */
     batchCreate(pins: CreatePinRequest[]): Promise<{
         created: Array<{
             id: string;
@@ -288,9 +516,6 @@ declare class PinsMethods {
             error: string;
         }>;
     }>;
-    /**
-     * Update multiple pins in a single request (max 50 pins)
-     */
     batchUpdate(updates: Array<{
         id: string;
     } & UpdatePinRequest>): Promise<{
@@ -301,9 +526,6 @@ declare class PinsMethods {
         }>;
         updated_at: number;
     }>;
-    /**
-     * Delete multiple pins in a single request (max 50 pins)
-     */
     batchDelete(pinIds: string[]): Promise<{
         deleted: string[];
         failed: Array<{
@@ -311,589 +533,46 @@ declare class PinsMethods {
             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'>>;
+    createEmbed(input: CreateEmbedPinInput): Promise<Pin<'embed'>>;
     /**
-     * Create a markdown pin (content comes from blocks)
-     */
-    createMarkdown(title: string, additionalMetadata?: Partial<CreatePinRequest['metadata']>): Promise<Pin>;
-    /**
-     * Create a stat card pin
-     */
-    createStatCard(data: {
-        title: string;
-        value: string | number;
-        change?: string;
-        icon?: string;
-    }, title: string, additionalMetadata?: Partial<CreatePinRequest['metadata']>): Promise<Pin>;
-    /**
-     * Create a flexible table pin
-     */
-    createTable(data: {
-        columns: Array<{
-            id: string;
-            label: string;
-            type?: string;
-        }>;
-        rows: Array<Record<string, any>>;
-    }, title: string, additionalMetadata?: Partial<CreatePinRequest['metadata']>): Promise<Pin>;
-    /**
-     * Create an embed pin (YouTube, Figma, etc.)
-     */
-    createEmbed(url: string, title: string, additionalMetadata?: Partial<CreatePinRequest['metadata']>): Promise<Pin>;
-}
-
-/**
- * Pinboards API Methods
- */
-
-declare class PinboardsMethods {
-    private client;
-    constructor(client: PindownClient);
-    /**
-     * Create a new pinboard
-     */
-    create(request: CreatePinboardRequest): Promise<Pinboard>;
-    /**
-     * Get a pinboard by ID
-     */
-    get(boardId: string): Promise<Pinboard>;
-    /**
-     * List all pinboards
-     */
-    list(): Promise<Pinboard[]>;
-    /**
-     * Update a pinboard
-     */
-    update(boardId: string, request: UpdatePinboardRequest): Promise<Pinboard>;
-    /**
-     * Delete a pinboard
-     */
-    delete(boardId: string): Promise<void>;
-    /**
-     * Add a pin to a pinboard
-     */
-    addPin(boardId: string, request: AddPinToPinboardRequest): Promise<Pinboard>;
-    /**
-     * Remove a pin from a pinboard
-     */
-    removePin(boardId: string, pinId: string): Promise<void>;
-    /**
-     * Update pinboard layout
-     */
-    updateLayout(boardId: string, request: UpdatePinboardLayoutRequest): Promise<Pinboard>;
-    /**
-     * Update pinboard sharing settings
-     */
-    share(boardId: string, request: {
-        is_public?: boolean;
-        require_sign_in?: boolean;
-        allow_comments?: boolean;
-    }): Promise<Pinboard>;
-    /**
-     * Get multiple pinboards by IDs in a single request (max 100 pinboards)
-     */
-    batchGet(pinboardIds: string[]): Promise<{
-        found: Pinboard[];
-        not_found: string[];
-        permission_denied: string[];
-    }>;
-    /**
-     * Add multiple pins to a pinboard with layout in a single request (max 50 pins)
-     */
-    batchAddPins(boardId: string, pinIds: string[], layout?: Record<string, {
-        x: number;
-        y: number;
-        w: number;
-        h: number;
-    }>): Promise<{
-        added: string[];
-        failed: Array<{
-            id: string;
-            error: string;
-        }>;
-        layout_updated: boolean;
-    }>;
-    /**
-     * Remove multiple pins from a pinboard in a single request (max 50 pins)
-     */
-    batchRemovePins(boardId: string, pinIds: string[]): Promise<{
-        removed: string[];
-        failed: Array<{
-            id: string;
-            error: string;
-        }>;
-    }>;
-    /**
-     * Create a custom role for a pinboard (max 5 roles per pinboard)
-     */
-    createRole(boardId: string, request: {
-        name: string;
-        color: string;
-        permissions?: Record<string, any>;
-    }): Promise<{
-        roleId: string;
-        name: string;
-        color: string;
-    }>;
-    /**
-     * List custom roles for a pinboard
-     */
-    listRoles(boardId: string): Promise<Record<string, any>>;
-    /**
-     * Update a custom role
-     */
-    updateRole(boardId: string, roleId: string, request: {
-        name?: string;
-        color?: string;
-        permissions?: Record<string, any>;
-    }): Promise<void>;
-    /**
-     * Delete a custom role
-     */
-    deleteRole(boardId: string, roleId: string): Promise<void>;
-    /**
-     * Assign custom roles to a user (user must be a collaborator first)
-     */
-    assignUserRoles(boardId: string, userId: string, roleIds: string[]): Promise<void>;
-    /**
-     * Set role requirements for a pin (only users with these roles can see the pin)
-     */
-    setPinRoleRequirements(boardId: string, pinId: string, roleIds: string[]): Promise<void>;
-}
-
-/**
- * Pages API Methods
- */
-
-declare class PagesMethods {
-    private client;
-    constructor(client: PindownClient);
-    /**
-     * Create a new page
-     */
-    create(request: CreatePageRequest): Promise<Page>;
-    /**
-     * Get a page by ID
-     */
-    get(pageId: string): Promise<Page>;
-    /**
-     * List all pages
-     */
-    list(options?: ListPagesOptions): Promise<{
-        pages: Page[];
-        total: number;
-    }>;
-    /**
-     * List pages shared with user
-     */
-    listShared(options?: ListPagesOptions): Promise<{
-        pages: Page[];
-        total: number;
-    }>;
-    /**
-     * Update a page
-     */
-    update(pageId: string, request: UpdatePageRequest): Promise<Page>;
-    /**
-     * Delete a page
-     */
-    delete(pageId: string): Promise<void>;
-    /**
-     * Add a pin to a page
-     */
-    addPin(pageId: string, request: AddPinToPageRequest): Promise<void>;
-    /**
-     * Remove a pin from a page
-     */
-    removePin(pageId: string, pinId: string): Promise<void>;
-    /**
-     * List pins in a page
-     */
-    listPins(pageId: string): Promise<{
-        pins: string[];
-        total: number;
-    }>;
-    /**
-     * Get multiple pages by IDs in a single request (max 100 pages)
-     */
-    batchGet(pageIds: string[]): Promise<{
-        found: Page[];
-        not_found: string[];
-        permission_denied: string[];
-    }>;
-    /**
-     * Create multiple pages in a single request (max 50 pages)
-     */
-    batchCreate(pages: CreatePageRequest[]): Promise<{
-        created: Array<{
-            id: string;
-            index: number;
-            created_at: number;
-        }>;
-        failed: Array<{
-            index: number;
-            error: string;
-        }>;
-    }>;
-    /**
-     * Update multiple pages in a single request (max 50 pages)
-     */
-    batchUpdate(updates: Array<{
-        id: string;
-    } & UpdatePageRequest>): Promise<{
-        updated: string[];
-        failed: Array<{
-            id: string;
-            error: string;
-        }>;
-        updated_at: number;
-    }>;
-    /**
-     * Delete multiple pages in a single request (max 50 pages)
-     */
-    batchDelete(pageIds: string[]): Promise<{
-        deleted: string[];
-        failed: Array<{
-            id: string;
-            error: string;
-        }>;
-    }>;
-}
-
-/**
- * Datasets API Methods
- */
-
-declare class DatasetsMethods {
-    private client;
-    constructor(client: PindownClient);
-    /**
-     * Create a new dataset
-     */
-    create(request: CreateDatasetRequest): Promise<Dataset>;
-    /**
-     * Get a dataset by ID
-     */
-    get(datasetId: string): Promise<Dataset>;
-    /**
-     * List all datasets
-     */
-    list(): Promise<Dataset[]>;
-    /**
-     * Update a dataset
-     */
-    update(datasetId: string, request: UpdateDatasetRequest): Promise<Dataset>;
-    /**
-     * Delete a dataset
-     */
-    delete(datasetId: string): Promise<void>;
-    /**
-     * Invite a collaborator to a dataset
-     */
-    inviteCollaborator(datasetId: string, request: {
-        email: string;
-        role: 'editor' | 'viewer';
-    }): Promise<{
-        email: string;
-        role: 'editor' | 'viewer';
-        inviteToken: string;
-        expiresAt: number;
-    }>;
-    /**
-     * Get multiple datasets by IDs in a single request (max 100 datasets)
-     */
-    batchGet(datasetIds: string[]): Promise<{
-        found: Dataset[];
-        not_found: string[];
-        permission_denied: string[];
-    }>;
-    /**
-     * Create multiple datasets in a single request (max 50 datasets)
-     */
-    batchCreate(datasets: Array<{
-        name: string;
-        schema?: any;
-        data?: any;
-        is_public?: boolean;
-    }>): Promise<{
-        created: Dataset[];
-        failed: Array<{
-            index: number;
-            error: string;
-        }>;
-    }>;
-    /**
-     * Update multiple datasets in a single request (max 50 datasets)
-     */
-    batchUpdate(updates: Array<{
-        id: string;
-        name?: string;
-        schema?: any;
-        data?: any;
-        is_public?: boolean;
-    }>): Promise<{
-        updated: string[];
-        failed: Array<{
-            id: string;
-            error: string;
-        }>;
-    }>;
-    /**
-     * Delete multiple datasets in a single request (max 50 datasets)
-     */
-    batchDelete(datasetIds: string[]): Promise<{
-        deleted: string[];
-        failed: Array<{
-            id: string;
-            error: string;
-        }>;
-    }>;
-}
-
-/**
- * Blocks API Methods
- */
-
-declare class BlocksMethods {
-    private client;
-    constructor(client: PindownClient);
-    /**
-     * Create a new block for a pin
-     */
-    create(pinId: string, request: CreateBlockRequest): Promise<Block>;
-    /**
-     * Get a block by ID
-     */
-    get(pinId: string, blockId: string): Promise<Block>;
-    /**
-     * List all blocks in a pin
-     */
-    list(pinId: string): Promise<Block[]>;
-    /**
-     * Update a block
-     */
-    update(pinId: string, blockId: string, request: UpdateBlockRequest): Promise<Block>;
-    /**
-     * Delete a block
-     */
-    delete(pinId: string, blockId: string): Promise<void>;
-    /**
-     * Get multiple blocks by IDs in a single request (max 100 blocks)
-     */
-    batchGet(blockIds: Array<{
-        pin_id: string;
-        block_id: string;
-    }>): Promise<{
-        found: Block[];
-        not_found: Array<{
-            pin_id: string;
-            block_id: string;
-        }>;
-        permission_denied: Array<{
-            pin_id: string;
-            block_id: string;
-        }>;
-    }>;
-    /**
-     * Create multiple blocks for a pin in a single request (max 50 blocks)
-     */
-    batchCreate(pinId: string, blocks: Array<{
-        title: string;
-        type?: 'markdown' | 'code' | 'text' | 'image';
-        template?: string;
-        order?: number;
-    }>): Promise<{
-        created: Block[];
-        failed: Array<{
-            index: number;
-            error: string;
-        }>;
-    }>;
-    /**
-     * Update multiple blocks in a single request (max 50 blocks)
+     * @deprecated Use createMarkdown({ title, content, ... }) — old signature ignored content in title
      */
-    batchUpdate(updates: Array<{
-        pin_id: string;
-        block_id: string;
-        title?: string;
-        type?: 'markdown' | 'code' | 'text' | 'image';
-        template?: string;
-        order?: number;
-    }>): Promise<{
-        updated: Array<{
-            pin_id: string;
-            block_id: string;
-        }>;
-        failed: Array<{
-            pin_id: string;
-            block_id: string;
-            error: string;
-        }>;
-    }>;
-    /**
-     * Delete multiple blocks in a single request (max 50 blocks)
-     */
-    batchDelete(blockIds: Array<{
-        pin_id: string;
-        block_id: string;
-    }>): Promise<{
-        deleted: Array<{
-            pin_id: string;
-            block_id: string;
-        }>;
-        failed: Array<{
-            pin_id: string;
-            block_id: string;
-            error: string;
-        }>;
-    }>;
+    createMarkdownLegacy(title: string, additionalMetadata?: Record<string, unknown>): Promise<Pin<'markdown'>>;
 }
 
 /**
- * Collaborators API Methods
+ * Configuration for the v1 Pins API client
  */
-
-declare class CollaboratorsMethods {
-    private client;
-    constructor(client: PindownClient);
-    /**
-     * List collaborators for a pin
-     */
-    listForPin(pinId: string): Promise<{
-        owner: Collaborator;
-        collaborators: Collaborator[];
-        pending_invites: Array<{
-            email: string;
-            role: string;
-            invited_at: string;
-        }>;
-    }>;
-    /**
-     * Invite a collaborator to a pin
-     */
-    inviteToPin(pinId: string, request: InviteCollaboratorRequest): Promise<void>;
-    /**
-     * Update a pin collaborator's role
-     */
-    updatePinRole(pinId: string, userId: string, request: UpdateCollaboratorRoleRequest): Promise<void>;
-    /**
-     * Remove a collaborator from a pin
-     */
-    removeFromPin(pinId: string, userId: string): Promise<void>;
-    /**
-     * Get current user's permissions for a pin
-     */
-    getPinPermissions(pinId: string): Promise<Permissions>;
-    /**
-     * List collaborators for a pinboard
-     */
-    listForPinboard(boardId: string): Promise<{
-        owner: Collaborator;
-        collaborators: Collaborator[];
-        pending_invites: Array<{
-            email: string;
-            role: string;
-            invited_at: string;
-        }>;
-    }>;
-    /**
-     * Invite a collaborator to a pinboard
-     */
-    inviteToPinboard(boardId: string, request: InviteCollaboratorRequest): Promise<void>;
-    /**
-     * Update a pinboard collaborator's role
-     */
-    updatePinboardRole(boardId: string, userId: string, request: UpdateCollaboratorRoleRequest): Promise<void>;
-    /**
-     * Remove a collaborator from a pinboard
-     */
-    removeFromPinboard(boardId: string, userId: string): Promise<void>;
-    /**
-     * Get current user's permissions for a pinboard
-     */
-    getPinboardPermissions(boardId: string): Promise<Permissions>;
-}
-
-/**
- * Configuration types for Pindown API Client
- */
-type Tier = 'starter' | 'hobby' | 'pro' | 'teams' | 'agency';
 interface PindownConfig {
-    /**
-     * Your Pindown API key (from https://pindown.ai/api-keys)
-     */
+    /** Workspace-plan API key from https://pindown.ai/api-keys */
     apiKey: string;
-    /**
-     * Your subscription tier (auto-detected from server if not provided)
-     * @internal Only use for testing - production should auto-detect
-     */
-    tier?: Tier;
-    /**
-     * Base URL for the API
-     * @default 'https://api.pindown.ai/v1'
-     */
+    /** @default 'https://api.pindown.ai/v1' */
     baseURL?: string;
-    /**
-     * Enable rate limit tracking
-     * @default true
-     */
-    enableRateLimitTracking?: boolean;
-    /**
-     * Maximum number of retry attempts for failed requests
-     * @default 3
-     */
+    /** @default 3 */
     maxRetries?: number;
-    /**
-     * Timeout for requests in milliseconds
-     * @default 30000 (30 seconds)
-     */
+    /** @default 30000 */
     timeout?: number;
 }
 
 /**
- * Pindown API Client
+ * Pindown API Client — v1 Pins API only
  */
 
 declare class PindownClient {
     private config;
-    private rateLimiter?;
-    private tierDetected;
     readonly pins: PinsMethods;
-    readonly pinboards: PinboardsMethods;
-    readonly pages: PagesMethods;
-    readonly datasets: DatasetsMethods;
-    readonly blocks: BlocksMethods;
-    readonly collaborators: CollaboratorsMethods;
     constructor(config: PindownConfig);
-    /**
-     * Core request method
-     */
-    request<T = any>(method: string, endpoint: string, data?: any): Promise<T>;
-    /**
-     * Handle error responses from API
-     */
+    request<T = unknown>(method: string, endpoint: string, data?: unknown): Promise<T>;
     private handleErrorResponse;
-    /**
-     * Detect tier from response headers
-     */
-    private detectTierFromHeaders;
-    /**
-     * Get current rate limit info
-     */
-    getRateLimitInfo(): RateLimitInfo | null;
-    /**
-     * Get current tier
-     */
-    getTier(): Tier | null;
-    /**
-     * Destroy the client (cleanup resources)
-     */
-    destroy(): void;
 }
 
 /**
- * Error classes for Pindown API Client
+ * Error classes for the v1 Pins API client
  */
-
 declare class PindownError extends Error {
     constructor(message: string);
 }
@@ -907,24 +586,11 @@ declare class NotFoundError extends PindownError {
     constructor(resource: string);
 }
 declare class ValidationError extends PindownError {
-    details?: any;
-    constructor(message: string, details?: any);
+    details?: unknown;
+    constructor(message: string, details?: unknown);
 }
 declare class RateLimitError extends PindownError {
-    window: 'minute' | 'hour';
-    limit: number;
-    used: number;
-    remaining: number;
-    resetAt: Date;
-    tier: Tier;
-    constructor(params: {
-        window: 'minute' | 'hour';
-        limit: number;
-        used: number;
-        remaining: number;
-        resetAt: Date;
-        tier: Tier;
-    });
+    constructor(message?: string);
 }
 declare class ServerError extends PindownError {
     statusCode: number;
@@ -934,4 +600,4 @@ declare class NetworkError extends PindownError {
     constructor(message?: string);
 }
 
-export { type AddPinToPageRequest, type AddPinToPinboardRequest, type ApiResponse, AuthenticationError, type Block, type BlockType, type Collaborator, type CollaboratorRole, type CreateBlockRequest, type CreateDatasetRequest, type CreatePageRequest, type CreatePinRequest, type CreatePinboardRequest, type Dataset, type DatasetType, ForbiddenError, type InviteCollaboratorRequest, type ListPagesOptions, type ListPinsOptions, NetworkError, NotFoundError, type Page, type PaginatedResponse, type Permissions, type Pin, type PinCardType, type PinDataType, type Pinboard, PindownClient, type PindownConfig, PindownError, RateLimitError, type RateLimitInfo, ServerError, type SharePinRequest, type Tier, type UpdateBlockRequest, type UpdateCollaboratorRoleRequest, type UpdateDatasetRequest, type UpdatePageRequest, type UpdatePinRequest, type UpdatePinboardLayoutRequest, type UpdatePinboardRequest, ValidationError };
+export { ALL_PIN_TYPES, type ApiResponse, AuthenticationError, type BusinessCardField, type BusinessCardPinConfig, type CalendarPinConfig, type ChartsPinConfig, type ChatPinConfig, type ChecklistItem, type ChecklistPinConfig, type CreateEmbedPinInput, type CreateMarkdownPinInput, type CreateNestedPinRequest, type CreatePinRequest, type CreateStatCardsPinInput, type CreateTablePinInput, type CreateTypedPinRequest, type CsvViewerPinConfig, type EmbedPinConfig, type ExcelViewerPinConfig, type FileUploadPinConfig, ForbiddenError, type GalleryImage, type GalleryPinConfig, type ImagePinConfig, type IntroPinConfig, type JsonListPinConfig, type JsonViewerPinConfig, type KanbanBoardPinConfig, type KanbanColumn, type LinkItem, type LinksPinConfig, type ListPinsOptions, type MarkdownPinConfig, type MastraPinConfig, type MermaidPinConfig, NetworkError, NotFoundError, PRODUCT_PIN_TYPES, type PaginatedResponse, type PdfViewerPinConfig, type Pin, type PinCardType, type PinConfigByType, type PinDataType, type PinLayout, type PinMetadata, type PinMetadataBase, type PinTypeId, PindownClient, type PindownConfig, PindownError, type ProductPinTypeId, type QrCodePinConfig, RateLimitError, type RealtimeCanvasPinConfig, type RoadmapPinConfig, ServerError, type SharePinRequest, type StatCardItem, type StatCardsPinConfig, type StepItem, type StepsPinConfig, type TableColumn, type TablePinConfig, type TableRow, type TextMediaPinConfig, type TimelinePinConfig, type UpdatePinRequest, type UserStoryPinConfig, ValidationError, type VideoPinConfig };