{"_id":"@drew-foxall/a2a-js-taskstore-core","name":"@drew-foxall/a2a-js-taskstore-core","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@drew-foxall/a2a-js-taskstore-core","version":"0.1.0","description":"Core types and utilities for A2A task store adapters","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./schemas":{"types":"./dist/schemas.d.ts","import":"./dist/schemas.js"}},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"dependencies":{"zod":"^3.24.0"},"peerDependencies":{"@a2a-js/sdk":"0.3.5"},"devDependencies":{"@a2a-js/sdk":"0.3.5","typescript":"^5.3.0"},"keywords":["a2a","agent2agent","taskstore","types"],"repository":{"type":"git","url":"git+https://github.com/drew-foxall/a2a-js-taskstore-adapters.git","directory":"packages/core"},"license":"MIT","author":{"name":"Drew Foxall"},"gitHead":"c29e6995c6f6268c2c89c57bb212cba7cfb51125","_id":"@drew-foxall/a2a-js-taskstore-core@0.1.0","bugs":{"url":"https://github.com/drew-foxall/a2a-js-taskstore-adapters/issues"},"homepage":"https://github.com/drew-foxall/a2a-js-taskstore-adapters#readme","_nodeVersion":"22.16.0","_npmVersion":"11.6.4","dist":{"integrity":"sha512-/9obBMnyj9v7AQz6zNgdCX8ULo+pVNWCRjX1bl52XgoQz0E3Zrn4DugBekIYCewHnX5kMR0GygLMNRWZZaJD9A==","shasum":"c218d32f529cf28adbceef83dcad42721b012d0f","tarball":"https://registry.npmjs.org/@drew-foxall/a2a-js-taskstore-core/-/a2a-js-taskstore-core-0.1.0.tgz","fileCount":22,"unpackedSize":94331,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIC3Hss5nWg9bdw4sAO89AwAt05Ff0TfXr6stGVOPebxfAiEAmb8je04+jxMG7Z1pxyx7RDV6UuS4gn3KJY1T2Nn/AdE="}]},"_npmUser":{"name":"drew-foxall","email":"drew@foxalltogether.com"},"directories":{},"maintainers":[{"name":"drew-foxall","email":"drew@foxalltogether.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/a2a-js-taskstore-core_0.1.0_1764769169455_0.21835717813810684"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-03T13:39:29.350Z","0.1.0":"2025-12-03T13:39:29.648Z","modified":"2025-12-03T13:39:29.920Z"},"maintainers":[{"name":"drew-foxall","email":"drew@foxalltogether.com"}],"description":"Core types and utilities for A2A task store adapters","homepage":"https://github.com/drew-foxall/a2a-js-taskstore-adapters#readme","keywords":["a2a","agent2agent","taskstore","types"],"repository":{"type":"git","url":"git+https://github.com/drew-foxall/a2a-js-taskstore-adapters.git","directory":"packages/core"},"author":{"name":"Drew Foxall"},"bugs":{"url":"https://github.com/drew-foxall/a2a-js-taskstore-adapters/issues"},"license":"MIT","readme":"# @drew-foxall/a2a-js-taskstore-core\n\nCore types and utilities for A2A task store adapters. Uses types from the official **@a2a-js/sdk** with **Zod** schemas for runtime validation.\n\n## Installation\n\n```bash\npnpm add @drew-foxall/a2a-js-taskstore-core @a2a-js/sdk@0.3.5\n```\n\n## SDK Version Compatibility\n\nThis package requires an **exact version** of `@a2a-js/sdk` as a peer dependency:\n\n| Core Version | SDK Version |\n|--------------|-------------|\n| 0.1.x        | 0.3.5       |\n\nThe 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.\n\n## Features\n\n- **Official types**: Re-exports types from `@a2a-js/sdk@0.3.5` for compatibility\n- **Compile-time verification**: Zod schemas use `satisfies` to match SDK types exactly\n- **Runtime validation**: Zod schemas validate data from storage backends\n- **Edge-compatible**: Works on Cloudflare Workers, Vercel Edge, Deno Deploy\n- **Extended interfaces**: Additional query capabilities beyond the base SDK\n- **Serialization helpers**: JSON serialization with validation\n- **Type-safe**: Single source of truth from SDK types with Zod validation\n\n## Overview\n\nThis package provides the shared foundation for all A2A task store adapters:\n\n- **Type re-exports** - Official A2A SDK types (`Task`, `TaskStore`, `PushNotificationConfig`, etc.)\n- **Zod schemas** - Runtime validation schemas matching SDK types\n- **Extended interfaces** - `ExtendedTaskStore` with additional query methods\n- **Serialization utilities** - Type-safe JSON serialization/deserialization with validation\n- **Validation utilities** - Input validation with detailed error messages\n\n## Types\n\nTypes are re-exported from the official `@a2a-js/sdk`:\n\n```typescript\nimport type {\n  // Task types (from @a2a-js/sdk)\n  Task,\n  TaskState,\n  TaskStatus,\n  Artifact,\n  Message,\n  Part,\n\n  // Store interfaces (from @a2a-js/sdk)\n  TaskStore,\n  PushNotificationStore,\n  PushNotificationConfig,\n\n  // Extended interfaces (from this package)\n  ExtendedTaskStore,\n  BaseStoreOptions,\n  TtlOptions,\n  ListTasksOptions,\n\n  // Utility types\n  ParseResult,\n  SafeParseResult,\n} from '@drew-foxall/a2a-js-taskstore-core';\n```\n\n## Zod Schemas\n\nZod schemas are provided for runtime validation. These schemas match the SDK types:\n\n```typescript\nimport {\n  TaskSchema,\n  TaskStateSchema,\n  TaskStatusSchema,\n  PushNotificationConfigSchema,\n  z,\n} from '@drew-foxall/a2a-js-taskstore-core';\n\n// Validate unknown data from storage\nconst result = TaskSchema.safeParse(unknownData);\nif (result.success) {\n  const task: Task = result.data;\n} else {\n  console.error('Validation failed:', result.error.issues);\n}\n\n// Parse and throw on invalid\nconst task = TaskSchema.parse(unknownData);\n```\n\n### Available Schemas\n\n```typescript\nimport {\n  // Task schemas\n  TaskSchema,\n  TaskStateSchema,\n  TaskStatusSchema,\n  ArtifactSchema,\n\n  // Message schemas\n  MessageSchema,\n  MessageRoleSchema,\n  PartSchema,\n  TextPartSchema,\n  FilePartSchema,\n  DataPartSchema,\n  FileContentSchema,\n\n  // Push notification schemas\n  PushNotificationConfigSchema,\n  PushNotificationConfigArraySchema,\n  PushAuthenticationSchema,\n\n  // Options schemas\n  BaseStoreOptionsSchema,\n  TtlOptionsSchema,\n  ListTasksOptionsSchema,\n} from '@drew-foxall/a2a-js-taskstore-core';\n```\n\n## Serialization\n\nType-safe JSON serialization with Zod validation:\n\n```typescript\nimport {\n  serializeTask,\n  parseTask,\n  safeParseTask,\n  parseTaskResult,\n} from '@drew-foxall/a2a-js-taskstore-core';\n\n// Serialize a task to JSON\nconst json = serializeTask(task);\n\n// Parse JSON with validation (throws on invalid)\nconst task = parseTask(json);\n\n// Safe parsing (returns undefined on failure)\nconst maybeTask = safeParseTask(json);\n\n// Result-based parsing (returns success/error object)\nconst result = parseTaskResult(json);\nif (result.success) {\n  console.log(result.data);\n} else {\n  console.error(result.error.issues);\n}\n```\n\n### Push Config Serialization\n\n```typescript\nimport {\n  serializePushConfigs,\n  parsePushConfigs,\n  safeParsePushConfigs,\n  parsePushConfig,\n  safeParsePushConfig,\n} from '@drew-foxall/a2a-js-taskstore-core';\n\n// Serialize configs to JSON\nconst json = serializePushConfigs(configs);\n\n// Parse with validation\nconst configs = parsePushConfigs(json);\n\n// Safe parsing (returns empty array on failure)\nconst configs = safeParsePushConfigs(json);\n```\n\n## Validation\n\nValidation utilities with detailed error messages:\n\n```typescript\nimport {\n  validateTask,\n  validateTaskId,\n  validatePushConfig,\n  validatePrefix,\n  validateTtl,\n  ValidationError,\n} from '@drew-foxall/a2a-js-taskstore-core';\n\ntry {\n  validateTask(unknownData);\n} catch (error) {\n  if (error instanceof ValidationError) {\n    console.error('Validation failed:', error.message);\n    console.error('Issues:', error.issues);\n    console.error('Path:', error.path);\n  }\n}\n\n// Individual field validation\nvalidateTaskId(id);       // throws if invalid\nvalidatePrefix(prefix);   // throws if invalid\nvalidateTtl(seconds);     // throws if invalid\n```\n\n### Type Guards\n\n```typescript\nimport {\n  isValidTask,\n  isValidPushConfig,\n  isValidTaskState,\n} from '@drew-foxall/a2a-js-taskstore-core';\n\nif (isValidTask(data)) {\n  // data is typed as Task\n}\n\nif (isValidTaskState(state)) {\n  // state is typed as TaskState\n}\n```\n\n### Factory Functions\n\nCreate custom validators from any Zod schema:\n\n```typescript\nimport {\n  createValidator,\n  createSafeValidator,\n  createParser,\n  createSafeParser,\n  z,\n} from '@drew-foxall/a2a-js-taskstore-core';\n\nconst MySchema = z.object({ name: z.string() });\n\n// Create an assertion function\nconst validate = createValidator(MySchema);\nvalidate(data); // throws if invalid\n\n// Create a type guard\nconst isValid = createSafeValidator(MySchema);\nif (isValid(data)) { /* data is typed */ }\n\n// Create a parser (throws)\nconst parse = createParser(MySchema);\nconst result = parse(data);\n\n// Create a safe parser (returns undefined)\nconst safeParse = createSafeParser(MySchema);\nconst maybeResult = safeParse(data);\n```\n\n## Store Interfaces\n\n### TaskStore (from @a2a-js/sdk)\n\n```typescript\ninterface TaskStore {\n  save(task: Task): Promise<void>;\n  load(taskId: string): Promise<Task | undefined>;\n}\n```\n\n### PushNotificationStore (from @a2a-js/sdk)\n\n```typescript\ninterface PushNotificationStore {\n  save(taskId: string, config: PushNotificationConfig): Promise<void>;\n  load(taskId: string): Promise<PushNotificationConfig[]>;\n  delete(taskId: string, configId?: string): Promise<void>;\n}\n```\n\n### ExtendedTaskStore (from this package)\n\nExtended interface with additional query capabilities:\n\n```typescript\ninterface ExtendedTaskStore extends TaskStore {\n  loadByContextId?(contextId: string): Promise<Task[]>;\n  loadByStatus?(status: TaskState, limit?: number): Promise<Task[]>;\n  delete?(taskId: string): Promise<void>;\n  list?(options?: ListTasksOptions): Promise<Task[]>;\n  countByStatus?(status: TaskState): Promise<number>;\n}\n```\n\n## Compatibility\n\nThis package is designed to work with the official [A2A JavaScript SDK](https://github.com/a2aproject/a2a-js) and addresses [Issue #114](https://github.com/a2aproject/a2a-js/issues/114) for persistent task storage.\n\nAll store implementations in this monorepo implement the official `TaskStore` and `PushNotificationStore` interfaces from `@a2a-js/sdk`.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-3fed1f29b3a44cc2aa111d6148bbc7c2"}