@pindownai/client-js 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,544 @@
+/**
+ * API Types for Pindown
+ */
+interface ApiResponse<T = any> {
+    success: boolean;
+    data: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+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 {
+    id: string;
+    user_id: string;
+    owner_id: string;
+    data_type: PinDataType;
+    pin_card_type?: PinCardType;
+    content: any;
+    metadata?: {
+        name?: string;
+        description?: string;
+        tags?: string[];
+        [key: string]: any;
+    };
+    is_public: boolean;
+    allow_edit: boolean;
+    require_sign_in: boolean;
+    allow_comments: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface CreatePinRequest {
+    data_type: PinDataType;
+    pin_card_type?: PinCardType;
+    content: any;
+    metadata?: Pin['metadata'];
+}
+interface UpdatePinRequest {
+    content?: any;
+    metadata?: Pin['metadata'];
+}
+interface SharePinRequest {
+    is_public?: boolean;
+    allow_edit?: boolean;
+    require_sign_in?: boolean;
+    allow_comments?: boolean;
+}
+interface ListPinsOptions {
+    limit?: number;
+    offset?: number;
+}
+interface Pinboard {
+    id: string;
+    user_id: string;
+    title: string;
+    description?: 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;
+}
+interface CreatePinboardRequest {
+    title: string;
+    description?: string;
+    tags?: string[];
+    layout?: Record<string, any>;
+    mobile_layout?: Record<string, any>;
+}
+interface UpdatePinboardRequest {
+    title?: string;
+    description?: string;
+    tags?: string[];
+    is_public?: boolean;
+    allow_comments?: boolean;
+    require_sign_in?: boolean;
+}
+interface AddPinToPinboardRequest {
+    pin_id: string;
+    position?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+interface UpdatePinboardLayoutRequest {
+    layout?: Record<string, any>;
+    mobile_layout?: Record<string, any>;
+}
+type DatasetType = 'json' | 'markdown';
+interface Dataset {
+    id: string;
+    user_id: string;
+    name: string;
+    type: DatasetType;
+    data: any;
+    description?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateDatasetRequest {
+    name: string;
+    type: DatasetType;
+    data: any;
+    description?: string;
+}
+interface UpdateDatasetRequest {
+    name?: string;
+    type?: DatasetType;
+    data?: any;
+    description?: string;
+}
+type BlockType = 'markdown' | 'mermaid' | 'conditional' | 'image' | 'stat-cards' | 'line-chart' | 'flexible-table' | 'embed';
+interface Block {
+    id: string;
+    pin_id: string;
+    name: string;
+    type: BlockType;
+    template: string | Record<string, any>;
+    order: number;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateBlockRequest {
+    name: string;
+    type: BlockType;
+    template: string | Record<string, any>;
+    order?: number;
+}
+interface UpdateBlockRequest {
+    name?: string;
+    type?: BlockType;
+    template?: string | Record<string, any>;
+    order?: number;
+}
+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;
+    };
+}
+
+/**
+ * Pins API Methods
+ */
+
+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
+     */
+    list(options?: ListPinsOptions): Promise<PaginatedResponse<Pin>>;
+    /**
+     * Update a pin
+     */
+    update(pinId: string, request: UpdatePinRequest): Promise<Pin>;
+    /**
+     * Delete a pin
+     */
+    delete(pinId: string): Promise<void>;
+    /**
+     * Update pin sharing settings
+     */
+    share(pinId: string, request: SharePinRequest): Promise<Pin>;
+    /**
+     * Create a markdown pin
+     */
+    createMarkdown(content: string, metadata?: CreatePinRequest['metadata']): Promise<Pin>;
+    /**
+     * Create a stat card pin
+     */
+    createStatCard(data: {
+        title: string;
+        value: string | number;
+        change?: string;
+        icon?: string;
+    }, metadata?: CreatePinRequest['metadata']): Promise<Pin>;
+    /**
+     * Create a flexible table pin
+     */
+    createTable(data: {
+        columns: Array<{
+            id: string;
+            label: string;
+            type?: string;
+        }>;
+        rows: Array<Record<string, any>>;
+    }, metadata?: CreatePinRequest['metadata']): Promise<Pin>;
+    /**
+     * Create an embed pin (YouTube, Figma, etc.)
+     */
+    createEmbed(url: string, metadata?: 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>;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * Collaborators API Methods
+ */
+
+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)
+     */
+    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/api/v1'
+     */
+    baseURL?: string;
+    /**
+     * Enable rate limit tracking
+     * @default true
+     */
+    enableRateLimitTracking?: boolean;
+    /**
+     * Maximum number of retry attempts for failed requests
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Timeout for requests in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+
+/**
+ * Pindown API Client
+ */
+
+declare class PindownClient {
+    private config;
+    private rateLimiter?;
+    private tierDetected;
+    readonly pins: PinsMethods;
+    readonly pinboards: PinboardsMethods;
+    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
+     */
+    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
+ */
+
+declare class PindownError extends Error {
+    constructor(message: string);
+}
+declare class AuthenticationError extends PindownError {
+    constructor(message?: string);
+}
+declare class ForbiddenError extends PindownError {
+    constructor(message?: string);
+}
+declare class NotFoundError extends PindownError {
+    constructor(resource: string);
+}
+declare class ValidationError extends PindownError {
+    details?: any;
+    constructor(message: string, details?: any);
+}
+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;
+    });
+}
+declare class ServerError extends PindownError {
+    statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+declare class NetworkError extends PindownError {
+    constructor(message?: string);
+}
+
+export { type AddPinToPinboardRequest, type ApiResponse, AuthenticationError, type Block, type BlockType, type Collaborator, type CollaboratorRole, type CreateBlockRequest, type CreateDatasetRequest, type CreatePinRequest, type CreatePinboardRequest, type Dataset, type DatasetType, ForbiddenError, type InviteCollaboratorRequest, type ListPinsOptions, NetworkError, NotFoundError, 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 UpdatePinRequest, type UpdatePinboardLayoutRequest, type UpdatePinboardRequest, ValidationError };