@drew-foxall/a2a-js-taskstore-core

Core types and utilities for A2A task store adapters. Uses types from the official @a2a-js/sdk with Zod schemas for runtime validation.

Installation

pnpm add @drew-foxall/a2a-js-taskstore-core @a2a-js/[email protected]

SDK Version Compatibility

This package requires an exact version of @a2a-js/sdk as a peer dependency:

| Core Version | SDK Version | |--------------|-------------| | 0.1.x | 0.3.5 |

The Zod schemas use TypeScript's satisfies keyword to ensure compile-time verification that they match the SDK types exactly. If the SDK types change, the build will fail until the schemas are updated.

Features

• Official types: Re-exports types from @a2a-js/[email protected] for compatibility
• Compile-time verification: Zod schemas use satisfies to match SDK types exactly
• Runtime validation: Zod schemas validate data from storage backends
• Edge-compatible: Works on Cloudflare Workers, Vercel Edge, Deno Deploy
• Extended interfaces: Additional query capabilities beyond the base SDK
• Serialization helpers: JSON serialization with validation
• Type-safe: Single source of truth from SDK types with Zod validation

Overview

This package provides the shared foundation for all A2A task store adapters:

• Type re-exports - Official A2A SDK types (Task, TaskStore, PushNotificationConfig, etc.)
• Zod schemas - Runtime validation schemas matching SDK types
• Extended interfaces - ExtendedTaskStore with additional query methods
• Serialization utilities - Type-safe JSON serialization/deserialization with validation
• Validation utilities - Input validation with detailed error messages

Types

Types are re-exported from the official @a2a-js/sdk:

import type {
  // Task types (from @a2a-js/sdk)
  Task,
  TaskState,
  TaskStatus,
  Artifact,
  Message,
  Part,

  // Store interfaces (from @a2a-js/sdk)
  TaskStore,
  PushNotificationStore,
  PushNotificationConfig,

  // Extended interfaces (from this package)
  ExtendedTaskStore,
  BaseStoreOptions,
  TtlOptions,
  ListTasksOptions,

  // Utility types
  ParseResult,
  SafeParseResult,
} from '@drew-foxall/a2a-js-taskstore-core';

Zod Schemas

Zod schemas are provided for runtime validation. These schemas match the SDK types:

import {
  TaskSchema,
  TaskStateSchema,
  TaskStatusSchema,
  PushNotificationConfigSchema,
  z,
} from '@drew-foxall/a2a-js-taskstore-core';

// Validate unknown data from storage
const result = TaskSchema.safeParse(unknownData);
if (result.success) {
  const task: Task = result.data;
} else {
  console.error('Validation failed:', result.error.issues);
}

// Parse and throw on invalid
const task = TaskSchema.parse(unknownData);

Available Schemas

import {
  // Task schemas
  TaskSchema,
  TaskStateSchema,
  TaskStatusSchema,
  ArtifactSchema,

  // Message schemas
  MessageSchema,
  MessageRoleSchema,
  PartSchema,
  TextPartSchema,
  FilePartSchema,
  DataPartSchema,
  FileContentSchema,

  // Push notification schemas
  PushNotificationConfigSchema,
  PushNotificationConfigArraySchema,
  PushAuthenticationSchema,

  // Options schemas
  BaseStoreOptionsSchema,
  TtlOptionsSchema,
  ListTasksOptionsSchema,
} from '@drew-foxall/a2a-js-taskstore-core';

Serialization

Type-safe JSON serialization with Zod validation:

import {
  serializeTask,
  parseTask,
  safeParseTask,
  parseTaskResult,
} from '@drew-foxall/a2a-js-taskstore-core';

// Serialize a task to JSON
const json = serializeTask(task);

// Parse JSON with validation (throws on invalid)
const task = parseTask(json);

// Safe parsing (returns undefined on failure)
const maybeTask = safeParseTask(json);

// Result-based parsing (returns success/error object)
const result = parseTaskResult(json);
if (result.success) {
  console.log(result.data);
} else {
  console.error(result.error.issues);
}

Push Config Serialization

import {
  serializePushConfigs,
  parsePushConfigs,
  safeParsePushConfigs,
  parsePushConfig,
  safeParsePushConfig,
} from '@drew-foxall/a2a-js-taskstore-core';

// Serialize configs to JSON
const json = serializePushConfigs(configs);

// Parse with validation
const configs = parsePushConfigs(json);

// Safe parsing (returns empty array on failure)
const configs = safeParsePushConfigs(json);

Validation

Validation utilities with detailed error messages:

import {
  validateTask,
  validateTaskId,
  validatePushConfig,
  validatePrefix,
  validateTtl,
  ValidationError,
} from '@drew-foxall/a2a-js-taskstore-core';

try {
  validateTask(unknownData);
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.message);
    console.error('Issues:', error.issues);
    console.error('Path:', error.path);
  }
}

// Individual field validation
validateTaskId(id);       // throws if invalid
validatePrefix(prefix);   // throws if invalid
validateTtl(seconds);     // throws if invalid

Type Guards

import {
  isValidTask,
  isValidPushConfig,
  isValidTaskState,
} from '@drew-foxall/a2a-js-taskstore-core';

if (isValidTask(data)) {
  // data is typed as Task
}

if (isValidTaskState(state)) {
  // state is typed as TaskState
}

Factory Functions

Create custom validators from any Zod schema:

import {
  createValidator,
  createSafeValidator,
  createParser,
  createSafeParser,
  z,
} from '@drew-foxall/a2a-js-taskstore-core';

const MySchema = z.object({ name: z.string() });

// Create an assertion function
const validate = createValidator(MySchema);
validate(data); // throws if invalid

// Create a type guard
const isValid = createSafeValidator(MySchema);
if (isValid(data)) { /* data is typed */ }

// Create a parser (throws)
const parse = createParser(MySchema);
const result = parse(data);

// Create a safe parser (returns undefined)
const safeParse = createSafeParser(MySchema);
const maybeResult = safeParse(data);

Store Interfaces

TaskStore (from @a2a-js/sdk)

interface TaskStore {
  save(task: Task): Promise<void>;
  load(taskId: string): Promise<Task | undefined>;
}

PushNotificationStore (from @a2a-js/sdk)

interface PushNotificationStore {
  save(taskId: string, config: PushNotificationConfig): Promise<void>;
  load(taskId: string): Promise<PushNotificationConfig[]>;
  delete(taskId: string, configId?: string): Promise<void>;
}

ExtendedTaskStore (from this package)

Extended interface with additional query capabilities:

interface ExtendedTaskStore extends TaskStore {
  loadByContextId?(contextId: string): Promise<Task[]>;
  loadByStatus?(status: TaskState, limit?: number): Promise<Task[]>;
  delete?(taskId: string): Promise<void>;
  list?(options?: ListTasksOptions): Promise<Task[]>;
  countByStatus?(status: TaskState): Promise<number>;
}

Compatibility

This package is designed to work with the official A2A JavaScript SDK and addresses Issue #114 for persistent task storage.

All store implementations in this monorepo implement the official TaskStore and PushNotificationStore interfaces from @a2a-js/sdk.

License

MIT