TypeScript

Guides

Install the TypeScript SDK: Add deepcrawl to your project with pnpm add deepcrawl, then import DeepcrawlApp to start making typed API calls.
Configure a typed client: Create a single server-side client with your API key and reuse it across Server Actions, Workers, or backend services.
Use generated schemas: Import schema exports from deepcrawl/schemas to validate request payloads and response data with Zod.
Share contract types: Reuse the definitions in deepcrawl/types to keep front-end and worker code in sync without duplicating interfaces.

Import Cheat Sheet

The deepcrawl/types entry point mirrors the package layout under packages/types. Import the groups you need and let TypeScript guide you.

Routers (API Endpoints) Types

/* Read endpoints */
import type {
  GetMarkdownOptions,
  GetMarkdownResponse,
  ReadUrlOptions,
  ReadUrlResponse,
} from 'deepcrawl/types';

/* Links endpoints */
import type {
  GetLinksOptions,
  GetLinksResponse,
  ExtractLinksOptions,
  ExtractLinksResponse,
} from 'deepcrawl/types';

/* Logs endpoints */
import type {
  ListLogsOptions,
  ListLogsResponse,
  GetOneLogOptions,
  GetOneLogResponse,
  ExportResponseOptions,
  ExportResponseOutput,
} from 'deepcrawl/types';

Services Types

// Services
import type {
  ScrapeOptions,
  MarkdownConverterOptions,
  LinkExtractionOptions,
  MetadataOptions,
} from 'deepcrawl/types';

Metrics Types

// Metrics
import type { MetricsOptions, Metrics } from 'deepcrawl/types';

Common Helpers Types

// Common helpers
import type {
  ActivityLogEntry,
  JoinedRequestPath,
  LinksTree,
  BaseSuccessResponse,
} from 'deepcrawl/types';

Utilities

// Utility functions
import {
  normalizeListLogsPagination,
  OptionalBoolWithDefault,
} from 'deepcrawl/types/utils';

const pagination = normalizeListLogsPagination({ limit: 150, offset: -5 });
const optionalFlagSchema = OptionalBoolWithDefault(true);

// OptionalBoolWithDefault
/**
 * Optional boolean schema with default value.
 * Convenient helper for common use case.
 *
 * @param defaultValue - The default boolean value
 * @returns Zod schema with boolean parsing and default
 */
export const OptionalBoolWithDefault = (defaultValue: boolean) =>
  z.boolean().default(defaultValue).optional();

// normalizeListLogsPagination
/**
 * @description Normalize list logs pagination input
 *
 * @param input - List logs pagination input
 * @returns Normalized list logs pagination
 *
 * @example
 * ```typescript
 * import { normalizeListLogsPagination } from '@deepcrawl/types/routers/logs/utils';
 *
 * const normalized = normalizeListLogsPagination({ limit: 150, offset: -5 });
 * // Returns: { limit: 100, offset: 0 } (clamped to valid ranges)
 * ```
 */
export function normalizeListLogsPagination(
  input: ListLogsPaginationInput = {},
): NormalizedListLogsPagination {
  const { limit, offset } = input;
  const limitNumber = Number(limit);
  const offsetNumber = Number(offset);
  const normalizedLimit = Number.isFinite(limitNumber)
    ? Math.min(Math.max(Math.trunc(limitNumber), 1), 100)
    : undefined;
  const normalizedOffset = Number.isFinite(offsetNumber)
    ? Math.max(Math.trunc(offsetNumber), 0)
    : undefined;
  return {
    limit: normalizedLimit,
    offset: normalizedOffset,
  };
}

TypeScript

Guides

Import Cheat Sheet

Routers (API Endpoints) Types

Services Types

Metrics Types

Common Helpers Types

Utilities

On this page