@stack0/sdk 0.2.0 → 0.2.1

package/dist/webdata/index.d.ts

@@ -0,0 +1,696 @@
+import { H as HttpClientConfig } from '../http-client-Wr9lXo9_.js';
+
+/**
+ * Type definitions for Stack0 Webdata API
+ */
+type Environment = "sandbox" | "production";
+type ScreenshotStatus = "pending" | "processing" | "completed" | "failed";
+type ScreenshotFormat = "png" | "jpeg" | "webp" | "pdf";
+type DeviceType = "desktop" | "tablet" | "mobile";
+interface Screenshot {
+    id: string;
+    organizationId: string;
+    projectId: string | null;
+    environment: Environment;
+    url: string;
+    format: ScreenshotFormat;
+    quality: number | null;
+    fullPage: boolean;
+    deviceType: DeviceType;
+    viewportWidth: number | null;
+    viewportHeight: number | null;
+    status: ScreenshotStatus;
+    imageUrl: string | null;
+    imageSize: number | null;
+    imageWidth: number | null;
+    imageHeight: number | null;
+    error: string | null;
+    processingTimeMs: number | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    completedAt: Date | null;
+}
+type ResourceType = "image" | "stylesheet" | "script" | "font" | "media" | "xhr" | "fetch" | "websocket";
+interface Clip {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface CreateScreenshotRequest {
+    url: string;
+    environment?: Environment;
+    projectId?: string;
+    format?: ScreenshotFormat;
+    quality?: number;
+    fullPage?: boolean;
+    deviceType?: DeviceType;
+    viewportWidth?: number;
+    viewportHeight?: number;
+    deviceScaleFactor?: number;
+    waitForSelector?: string;
+    waitForTimeout?: number;
+    blockAds?: boolean;
+    blockCookieBanners?: boolean;
+    blockChatWidgets?: boolean;
+    blockTrackers?: boolean;
+    blockUrls?: string[];
+    blockResources?: ResourceType[];
+    darkMode?: boolean;
+    customCss?: string;
+    customJs?: string;
+    headers?: Record<string, string>;
+    cookies?: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+    }>;
+    selector?: string;
+    hideSelectors?: string[];
+    clickSelector?: string;
+    omitBackground?: boolean;
+    userAgent?: string;
+    clip?: Clip;
+    thumbnailWidth?: number;
+    thumbnailHeight?: number;
+    cacheKey?: string;
+    cacheTtl?: number;
+    webhookUrl?: string;
+    webhookSecret?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateScreenshotResponse {
+    id: string;
+    status: ScreenshotStatus;
+}
+interface GetScreenshotRequest {
+    id: string;
+    environment?: Environment;
+    projectId?: string;
+}
+interface ListScreenshotsRequest {
+    environment?: Environment;
+    projectId?: string;
+    status?: ScreenshotStatus;
+    url?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface ListScreenshotsResponse {
+    items: Screenshot[];
+    nextCursor?: string;
+}
+type ExtractionStatus = "pending" | "processing" | "completed" | "failed";
+type ExtractionMode = "auto" | "schema" | "markdown" | "raw";
+interface PageMetadata {
+    title?: string;
+    description?: string;
+    ogImage?: string;
+    favicon?: string;
+    links?: string[];
+    images?: string[];
+}
+interface Extraction {
+    id: string;
+    organizationId: string;
+    projectId: string | null;
+    environment: Environment;
+    url: string;
+    mode: string;
+    status: ExtractionStatus;
+    extractedData: Record<string, unknown> | null;
+    markdown: string | null;
+    rawHtml: string | null;
+    pageMetadata: PageMetadata | null;
+    error: string | null;
+    processingTimeMs: number | null;
+    tokensUsed: number | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    completedAt: Date | null;
+}
+interface CreateExtractionRequest {
+    url: string;
+    environment?: Environment;
+    projectId?: string;
+    mode?: ExtractionMode;
+    schema?: Record<string, unknown>;
+    prompt?: string;
+    includeLinks?: boolean;
+    includeImages?: boolean;
+    includeMetadata?: boolean;
+    waitForSelector?: string;
+    waitForTimeout?: number;
+    headers?: Record<string, string>;
+    cookies?: Array<{
+        name: string;
+        value: string;
+        domain?: string;
+    }>;
+    webhookUrl?: string;
+    webhookSecret?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateExtractionResponse {
+    id: string;
+    status: ExtractionStatus;
+}
+interface GetExtractionRequest {
+    id: string;
+    environment?: Environment;
+    projectId?: string;
+}
+interface ListExtractionsRequest {
+    environment?: Environment;
+    projectId?: string;
+    status?: ExtractionStatus;
+    url?: string;
+    limit?: number;
+    cursor?: string;
+}
+interface ListExtractionsResponse {
+    items: Extraction[];
+    nextCursor?: string;
+}
+type ScheduleFrequency = "hourly" | "daily" | "weekly" | "monthly";
+type ScheduleType = "screenshot" | "extraction";
+interface Schedule {
+    id: string;
+    organizationId: string;
+    projectId: string | null;
+    environment: Environment;
+    name: string;
+    url: string;
+    type: ScheduleType;
+    frequency: ScheduleFrequency;
+    config: Record<string, unknown>;
+    isActive: boolean;
+    detectChanges: boolean;
+    changeThreshold: number | null;
+    webhookUrl: string | null;
+    totalRuns: number;
+    successfulRuns: number;
+    failedRuns: number;
+    lastRunAt: Date | null;
+    nextRunAt: Date | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface CreateScheduleRequest {
+    name: string;
+    url: string;
+    type: ScheduleType;
+    environment?: Environment;
+    projectId?: string;
+    frequency?: ScheduleFrequency;
+    config: Record<string, unknown>;
+    detectChanges?: boolean;
+    changeThreshold?: number;
+    webhookUrl?: string;
+    webhookSecret?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateScheduleResponse {
+    id: string;
+}
+interface UpdateScheduleRequest {
+    id: string;
+    environment?: Environment;
+    projectId?: string;
+    name?: string;
+    frequency?: ScheduleFrequency;
+    config?: Record<string, unknown>;
+    isActive?: boolean;
+    detectChanges?: boolean;
+    changeThreshold?: number;
+    webhookUrl?: string | null;
+    webhookSecret?: string | null;
+    metadata?: Record<string, unknown>;
+}
+interface GetScheduleRequest {
+    id: string;
+    environment?: Environment;
+    projectId?: string;
+}
+interface ListSchedulesRequest {
+    environment?: Environment;
+    projectId?: string;
+    type?: ScheduleType;
+    isActive?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+interface ListSchedulesResponse {
+    items: Schedule[];
+    nextCursor?: string;
+}
+interface Usage {
+    periodStart: Date;
+    periodEnd: Date;
+    screenshotsTotal: number;
+    screenshotsSuccessful: number;
+    screenshotsFailed: number;
+    screenshotCreditsUsed: number;
+    extractionsTotal: number;
+    extractionsSuccessful: number;
+    extractionsFailed: number;
+    extractionCreditsUsed: number;
+    extractionTokensUsed: number;
+    batchJobsTotal: number;
+    batchUrlsProcessed: number;
+}
+interface GetUsageRequest {
+    environment?: Environment;
+    periodStart?: string;
+    periodEnd?: string;
+}
+type BatchJobStatus = "pending" | "processing" | "completed" | "failed" | "cancelled";
+type BatchJobType = "screenshot" | "extraction";
+interface BatchJob {
+    id: string;
+    organizationId: string;
+    projectId: string | null;
+    environment: Environment;
+    type: BatchJobType;
+    name: string | null;
+    status: BatchJobStatus;
+    urls: string[];
+    config: Record<string, unknown>;
+    totalUrls: number;
+    processedUrls: number;
+    successfulUrls: number;
+    failedUrls: number;
+    webhookUrl: string | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    startedAt: Date | null;
+    completedAt: Date | null;
+}
+interface CreateBatchScreenshotsRequest {
+    urls: string[];
+    environment?: Environment;
+    projectId?: string;
+    name?: string;
+    config?: {
+        format?: ScreenshotFormat;
+        quality?: number;
+        fullPage?: boolean;
+        deviceType?: DeviceType;
+        viewportWidth?: number;
+        viewportHeight?: number;
+        blockAds?: boolean;
+        blockCookieBanners?: boolean;
+        waitForSelector?: string;
+        waitForTimeout?: number;
+    };
+    webhookUrl?: string;
+    webhookSecret?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateBatchExtractionsRequest {
+    urls: string[];
+    environment?: Environment;
+    projectId?: string;
+    name?: string;
+    config?: {
+        mode?: ExtractionMode;
+        schema?: Record<string, unknown>;
+        prompt?: string;
+        includeLinks?: boolean;
+        includeImages?: boolean;
+        includeMetadata?: boolean;
+        waitForSelector?: string;
+        waitForTimeout?: number;
+    };
+    webhookUrl?: string;
+    webhookSecret?: string;
+    metadata?: Record<string, unknown>;
+}
+interface CreateBatchResponse {
+    id: string;
+    status: BatchJobStatus;
+    totalUrls: number;
+}
+interface GetBatchJobRequest {
+    id: string;
+    environment?: Environment;
+    projectId?: string;
+}
+interface ListBatchJobsRequest {
+    environment?: Environment;
+    projectId?: string;
+    status?: BatchJobStatus;
+    type?: BatchJobType;
+    limit?: number;
+    cursor?: string;
+}
+interface ListBatchJobsResponse {
+    items: BatchJob[];
+    nextCursor?: string;
+}
+
+/**
+ * Stack0 Webdata Client
+ * Capture screenshots and extract data from web pages
+ */
+
+declare class Webdata {
+    private http;
+    constructor(config: HttpClientConfig);
+    /**
+     * Capture a screenshot of a URL
+     *
+     * @example
+     * ```typescript
+     * const { id, status } = await webdata.screenshot({
+     *   url: 'https://example.com',
+     *   format: 'png',
+     *   fullPage: true,
+     *   deviceType: 'desktop',
+     * });
+     *
+     * // Poll for completion
+     * const screenshot = await webdata.getScreenshot({ id });
+     * console.log(screenshot.imageUrl);
+     * ```
+     */
+    screenshot(request: CreateScreenshotRequest): Promise<CreateScreenshotResponse>;
+    /**
+     * Get a screenshot by ID
+     *
+     * @example
+     * ```typescript
+     * const screenshot = await webdata.getScreenshot({ id: 'screenshot-id' });
+     * if (screenshot.status === 'completed') {
+     *   console.log(screenshot.imageUrl);
+     * }
+     * ```
+     */
+    getScreenshot(request: GetScreenshotRequest): Promise<Screenshot>;
+    /**
+     * List screenshots with pagination and filters
+     *
+     * @example
+     * ```typescript
+     * const { items, nextCursor } = await webdata.listScreenshots({
+     *   status: 'completed',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    listScreenshots(request?: ListScreenshotsRequest): Promise<ListScreenshotsResponse>;
+    /**
+     * Delete a screenshot
+     *
+     * @example
+     * ```typescript
+     * await webdata.deleteScreenshot({ id: 'screenshot-id' });
+     * ```
+     */
+    deleteScreenshot(request: GetScreenshotRequest): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Capture a screenshot and wait for completion
+     *
+     * @example
+     * ```typescript
+     * const screenshot = await webdata.screenshotAndWait({
+     *   url: 'https://example.com',
+     *   format: 'png',
+     * });
+     * console.log(screenshot.imageUrl);
+     * ```
+     */
+    screenshotAndWait(request: CreateScreenshotRequest, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<Screenshot>;
+    /**
+     * Extract content from a URL
+     *
+     * @example
+     * ```typescript
+     * const { id, status } = await webdata.extract({
+     *   url: 'https://example.com/article',
+     *   mode: 'markdown',
+     *   includeMetadata: true,
+     * });
+     *
+     * // Poll for completion
+     * const extraction = await webdata.getExtraction({ id });
+     * console.log(extraction.markdown);
+     * ```
+     */
+    extract(request: CreateExtractionRequest): Promise<CreateExtractionResponse>;
+    /**
+     * Get an extraction by ID
+     *
+     * @example
+     * ```typescript
+     * const extraction = await webdata.getExtraction({ id: 'extraction-id' });
+     * if (extraction.status === 'completed') {
+     *   console.log(extraction.markdown);
+     *   console.log(extraction.pageMetadata);
+     * }
+     * ```
+     */
+    getExtraction(request: GetExtractionRequest): Promise<Extraction>;
+    /**
+     * List extractions with pagination and filters
+     *
+     * @example
+     * ```typescript
+     * const { items, nextCursor } = await webdata.listExtractions({
+     *   status: 'completed',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    listExtractions(request?: ListExtractionsRequest): Promise<ListExtractionsResponse>;
+    /**
+     * Delete an extraction
+     *
+     * @example
+     * ```typescript
+     * await webdata.deleteExtraction({ id: 'extraction-id' });
+     * ```
+     */
+    deleteExtraction(request: GetExtractionRequest): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Extract content and wait for completion
+     *
+     * @example
+     * ```typescript
+     * const extraction = await webdata.extractAndWait({
+     *   url: 'https://example.com/article',
+     *   mode: 'markdown',
+     * });
+     * console.log(extraction.markdown);
+     * ```
+     */
+    extractAndWait(request: CreateExtractionRequest, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<Extraction>;
+    /**
+     * Create a scheduled screenshot or extraction job
+     *
+     * @example
+     * ```typescript
+     * const { id } = await webdata.createSchedule({
+     *   name: 'Daily homepage screenshot',
+     *   url: 'https://example.com',
+     *   type: 'screenshot',
+     *   frequency: 'daily',
+     *   config: { format: 'png', fullPage: true },
+     * });
+     * ```
+     */
+    createSchedule(request: CreateScheduleRequest): Promise<CreateScheduleResponse>;
+    /**
+     * Update a schedule
+     *
+     * @example
+     * ```typescript
+     * await webdata.updateSchedule({
+     *   id: 'schedule-id',
+     *   frequency: 'weekly',
+     *   isActive: false,
+     * });
+     * ```
+     */
+    updateSchedule(request: UpdateScheduleRequest): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get a schedule by ID
+     *
+     * @example
+     * ```typescript
+     * const schedule = await webdata.getSchedule({ id: 'schedule-id' });
+     * console.log(schedule.nextRunAt);
+     * ```
+     */
+    getSchedule(request: GetScheduleRequest): Promise<Schedule>;
+    /**
+     * List schedules with pagination and filters
+     *
+     * @example
+     * ```typescript
+     * const { items, nextCursor } = await webdata.listSchedules({
+     *   type: 'screenshot',
+     *   isActive: true,
+     * });
+     * ```
+     */
+    listSchedules(request?: ListSchedulesRequest): Promise<ListSchedulesResponse>;
+    /**
+     * Delete a schedule
+     *
+     * @example
+     * ```typescript
+     * await webdata.deleteSchedule({ id: 'schedule-id' });
+     * ```
+     */
+    deleteSchedule(request: GetScheduleRequest): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Toggle a schedule on or off
+     *
+     * @example
+     * ```typescript
+     * const { isActive } = await webdata.toggleSchedule({ id: 'schedule-id' });
+     * console.log(`Schedule is now ${isActive ? 'active' : 'paused'}`);
+     * ```
+     */
+    toggleSchedule(request: GetScheduleRequest): Promise<{
+        isActive: boolean;
+    }>;
+    /**
+     * Get usage statistics
+     *
+     * @example
+     * ```typescript
+     * const usage = await webdata.getUsage({
+     *   periodStart: '2024-01-01T00:00:00Z',
+     *   periodEnd: '2024-01-31T23:59:59Z',
+     * });
+     * console.log(`Screenshots: ${usage.screenshotsTotal}`);
+     * console.log(`Extractions: ${usage.extractionsTotal}`);
+     * ```
+     */
+    getUsage(request?: GetUsageRequest): Promise<Usage>;
+    /**
+     * Create a batch screenshot job for multiple URLs
+     *
+     * @example
+     * ```typescript
+     * const { id, totalUrls } = await webdata.batchScreenshots({
+     *   urls: [
+     *     'https://example.com',
+     *     'https://example.org',
+     *   ],
+     *   config: { format: 'png', fullPage: true },
+     * });
+     *
+     * // Poll for completion
+     * const job = await webdata.getBatchJob({ id });
+     * console.log(`Progress: ${job.processedUrls}/${job.totalUrls}`);
+     * ```
+     */
+    batchScreenshots(request: CreateBatchScreenshotsRequest): Promise<CreateBatchResponse>;
+    /**
+     * Create a batch extraction job for multiple URLs
+     *
+     * @example
+     * ```typescript
+     * const { id, totalUrls } = await webdata.batchExtractions({
+     *   urls: [
+     *     'https://example.com/article1',
+     *     'https://example.com/article2',
+     *   ],
+     *   config: { mode: 'markdown' },
+     * });
+     * ```
+     */
+    batchExtractions(request: CreateBatchExtractionsRequest): Promise<CreateBatchResponse>;
+    /**
+     * Get a batch job by ID
+     *
+     * @example
+     * ```typescript
+     * const job = await webdata.getBatchJob({ id: 'batch-id' });
+     * console.log(`Status: ${job.status}`);
+     * console.log(`Progress: ${job.processedUrls}/${job.totalUrls}`);
+     * ```
+     */
+    getBatchJob(request: GetBatchJobRequest): Promise<BatchJob>;
+    /**
+     * List batch jobs with pagination and filters
+     *
+     * @example
+     * ```typescript
+     * const { items, nextCursor } = await webdata.listBatchJobs({
+     *   status: 'completed',
+     *   type: 'screenshot',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    listBatchJobs(request?: ListBatchJobsRequest): Promise<ListBatchJobsResponse>;
+    /**
+     * Cancel a batch job
+     *
+     * @example
+     * ```typescript
+     * await webdata.cancelBatchJob({ id: 'batch-id' });
+     * ```
+     */
+    cancelBatchJob(request: GetBatchJobRequest): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Create a batch screenshot job and wait for completion
+     *
+     * @example
+     * ```typescript
+     * const job = await webdata.batchScreenshotsAndWait({
+     *   urls: ['https://example.com', 'https://example.org'],
+     *   config: { format: 'png' },
+     * });
+     * console.log(`Completed: ${job.successfulUrls} successful, ${job.failedUrls} failed`);
+     * ```
+     */
+    batchScreenshotsAndWait(request: CreateBatchScreenshotsRequest, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<BatchJob>;
+    /**
+     * Create a batch extraction job and wait for completion
+     *
+     * @example
+     * ```typescript
+     * const job = await webdata.batchExtractionsAndWait({
+     *   urls: ['https://example.com/article1', 'https://example.com/article2'],
+     *   config: { mode: 'markdown' },
+     * });
+     * console.log(`Completed: ${job.successfulUrls} successful`);
+     * ```
+     */
+    batchExtractionsAndWait(request: CreateBatchExtractionsRequest, options?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<BatchJob>;
+    private convertScreenshotDates;
+    private convertExtractionDates;
+    private convertScheduleDates;
+    private convertUsageDates;
+    private convertBatchJobDates;
+}
+
+export { type BatchJob, type BatchJobStatus, type BatchJobType, type Clip, type CreateBatchExtractionsRequest, type CreateBatchResponse, type CreateBatchScreenshotsRequest, type CreateExtractionRequest, type CreateExtractionResponse, type CreateScheduleRequest, type CreateScheduleResponse, type CreateScreenshotRequest, type CreateScreenshotResponse, type DeviceType, type Environment, type Extraction, type ExtractionMode, type ExtractionStatus, type GetBatchJobRequest, type GetExtractionRequest, type GetScheduleRequest, type GetScreenshotRequest, type GetUsageRequest, type ListBatchJobsRequest, type ListBatchJobsResponse, type ListExtractionsRequest, type ListExtractionsResponse, type ListSchedulesRequest, type ListSchedulesResponse, type ListScreenshotsRequest, type ListScreenshotsResponse, type PageMetadata, type ResourceType, type Schedule, type ScheduleFrequency, type ScheduleType, type Screenshot, type ScreenshotFormat, type ScreenshotStatus, type UpdateScheduleRequest, type Usage, Webdata };