Grabba TypeScript SDK

Grabba TypeScript SDK provides a simple and intuitive interface for scheduling web data extraction jobs, retrieving job results, and managing your extraction workflows.

Installation

Install the SDK using npm:

npm i grabba

Basic Setup

Import the client and required types

import {
  Grabba, Job,
  JobNavigationType, JobSchedulePolicy, JobTaskType,
  KnowledgeBase, ContextResult
} from 'grabba';

Initialize a client instance

const grabba = new Grabba('your-api-key', {
  region: PuppetRegion.US, // Optional: Defaults to US
});

Methods

extract

extract(job: Job): Promise<{ respObj: JobExecutionResponse }>

Schedules a new web data extraction job.

Example:

const job = {
  url: 'https://docs.grabba.dev/home',
  schedule: { policy: JobSchedulePolicy.immediately },
  navigation: { type: JobNavigationType.none },
  tasks: [
    {
      type: JobTaskType.webPageAsMarkdown,
    },
  ]
};

const { status, message, jobResult } = await grabba.extract(job);
console.log(`Job completed with status: ${status}`);

createJob

createJob(job: Job): Promise<JobCreationResponse>

Creates a job without executing it immediately.

Example:

const response = await grabba.createJob(job);
console.log(`Job created with ID: ${response.jobId}`);

estimateCost

estimateCost(job: Job): Promise<JobEstimatedCostResponse>

Estimates the cost of running a given extraction job.

Example:

const estimate = await grabba.estimateCost(job);
console.log(`Estimated token cost: ${estimate.tokensRequired}`);

scheduleJob

scheduleJob(jobId: string): Promise<{ respObj: JobExecutionResponse }>

Schedules an existing job for execution.

Example:

const { status, message, jobResult } = await grabba.scheduleJob('12345');
console.log(`Job completed with status: ${status}`);

getJobs

getJobs(): Promise<GetJobsResponse>

Retrieves a list of all jobs associated with the API key.

Example:

const jobs = await grabba.getJobs();

getJob

getJob(jobId: string): Promise<GetJobResponse>

Retrieves details of a specific job by its ID.

Example:

const job = await grabba.getJob('12345');

deleteJob

deleteJob(jobId: string): Promise<BaseResponse>

Deletes a specific job by its ID.

Example:

const result = await grabba.deleteJob('67890');
console.log(result);

getJobResult

getJobResult(jobResultId: string): Promise<GetJobResultResponse>

Retrieves the results of a specific job by its result ID.

Example:

const result = await grabba.getJobResult('67890');
console.log(result);

deleteJobResult

deleteJobResult(jobResultId: string): Promise<BaseResponse>

Deletes a specific job result by its ID.

Example:

const result = await grabba.deleteJobResult('67890');
console.log(result);

getStats

getStats(): Promise<JobStats>

Retrieves summary statistics of jobs executed under your API key.

Example:

const stats = await grabba.getStats();
console.log(stats);

Knowledge Base Methods

createKnowledgeBase

createKnowledgeBase(name: string, description?: string): Promise<CreateKnowledgeBaseResponse>

Creates a new knowledge base.

Example:

const { knowledgeBase } = await grabba.createKnowledgeBase('My First KB', 'This is a test knowledge base.');
console.log(`Knowledge Base created with ID: ${knowledgeBase.id}`);

getKnowledgeBases

getKnowledgeBases(): Promise<GetKnowledgeBasesResponse>

Retrieves a list of all your knowledge bases.

Example:

const { knowledgeBases } = await grabba.getKnowledgeBases();
console.log(knowledgeBases);

getKnowledgeBase

getKnowledgeBase(kbId: string): Promise<GetKnowledgeBaseResponse>

Retrieves a specific knowledge base by its ID.

Example:

const { knowledgeBase } = await grabba.getKnowledgeBase('kb-123');
console.log(knowledgeBase);

deleteKnowledgeBase

deleteKnowledgeBase(kbId: string): Promise<BaseResponse>

Deletes a specific knowledge base by its ID.

Example:

const response = await grabba.deleteKnowledgeBase('kb-123');
console.log(response.message);

storeContext

storeContext(kbId: string, context: string, metadata?: Record<string, any>): Promise<StoreContextResponse>

Stores a new context (piece of information) into a knowledge base. The context will be automatically chunked and embedded.

Example:

const { contextIds } = await grabba.storeContext(
  'kb-123',
  'Grabba is an awesome web data platform.',
  { source: 'internal-docs' }
);
console.log(`Context stored with IDs: ${contextIds.join(', ')}`);

fetchContext

fetchContext(kbId: string, query: string, options?: any): Promise<FetchContextResponse>

Fetches relevant context from a knowledge base based on a semantic query.

Example:

const { results } = await grabba.fetchContext('kb-123', 'What is Grabba?');
console.log(results);

updateContext

updateContext(contextId: string, content?: string, metadata?: Record<string, any>): Promise<UpdateContextResponse>

Updates a specific context entry by its ID.

Example:

const { context } = await grabba.updateContext('ctx-123', 'Grabba is a powerful web data platform.');
console.log('Updated context:', context);

deleteContext

deleteContext(contextId: string): Promise<BaseResponse>

Deletes a specific context entry by its ID.

Example:

const response = await grabba.deleteContext('ctx-123');
console.log(response.message);

gatherContext

gatherContext(kbId: string): Promise<GatherContextResponse>

Gathers and returns all unique metadata tags and values for a given knowledge base.

Example:

const { metadata } = await grabba.gatherContext('kb-123');
console.log('Available metadata tags:', metadata);

Types

Job

Represents a web data extraction job.

interface Job {
  url: string;
  tasks: JobTask[];
  schedule: JobSchedule;
  navigation: JobNavigation;
  puppetConfig?: IWebAgentConfig;
}

JobTask

Represents a single task in an extraction job.

interface JobTask {
  type: JobTaskType;
  options?: JobTaskOptions;
}

JobTaskType

Enumeration of available job task types.

enum JobTaskType {
  webPageAsHTML = 'webPageAsHTML',
  webPageMetadata = 'webPageMetadata',
  webScreenCapture = 'webScreenCapture',
  webPageAsMarkdown = 'webPageAsMarkdown',
  specificDataExtraction = 'specificDataExtraction',
}

JobResult

Represents the result of a job.

interface JobResult {
  id: string;
  output: Record<string, JobTaskOutput>;
  startTime: Date;
  stopTime: Date;
  duration: string;
}

IWebAgentConfig

Configuration for Web Agent.

interface IWebAgentConfig {
  region: PuppetRegion;
  deviceType?: PuppetDeviceType;
  viewport?: PuppetViewport;
}

KnowledgeBase

Represents a knowledge base.

interface KnowledgeBase {
  id: string;
  userId: string;
  name: string;
  description?: string;
  sizeInBytes: number;
  maxSizeInBytes: number;
  createdAt: Date;
}

ContextResult

Represents a chunk of context retrieved from a knowledge base.

interface ContextResult {
  id: string;
  kbId: string;
  source: string;
  sourceType: string;
  chunkIndex: number;
  content: string;
  metadata: Record<string, any>;
  createdAt: Date;
}

Error Handling

The SDK throws errors for:

• Invalid API keys
• Failed API requests
• Missing or invalid parameters

Example:

try {
  const { status, message, jobResult } = await grabba.extract(job);
  if (status === "success") {
    const { data } = jobResult;
    console.log("results data: ", data);
  }
  else {
    // status === "error"
    console.log("Error message: ", message);
  }
} catch (err) {
  console.log("Error: ", err)
};

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.