{"id":45207790,"url":"https://github.com/aipartnerup/apcore-typescript","last_synced_at":"2026-03-12T08:49:54.697Z","repository":{"id":338796900,"uuid":"1158471673","full_name":"aipartnerup/apcore-typescript","owner":"aipartnerup","description":"A schema-driven module development framework for TypeScript.","archived":false,"fork":false,"pushed_at":"2026-03-06T08:47:12.000Z","size":609,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T12:48:29.443Z","etag":null,"topics":["agent-executor-javascript","ai","ai-agent-javascript","ai-agent-js","ai-agent-typescript","ai-perceivable-typescript","aiagentframework","apcore","api-specification"],"latest_commit_sha":null,"homepage":"https://aipartnerup.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aipartnerup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-15T12:35:24.000Z","updated_at":"2026-03-06T08:42:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aipartnerup/apcore-typescript","commit_stats":null,"previous_names":["aipartnerup/apcore-typescript"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/aipartnerup/apcore-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aipartnerup%2Fapcore-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aipartnerup%2Fapcore-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aipartnerup%2Fapcore-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aipartnerup%2Fapcore-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aipartnerup","download_url":"https://codeload.github.com/aipartnerup/apcore-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aipartnerup%2Fapcore-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30243581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"online","status_checked_at":"2026-03-08T02:00:06.215Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-executor-javascript","ai","ai-agent-javascript","ai-agent-js","ai-agent-typescript","ai-perceivable-typescript","aiagentframework","apcore","api-specification"],"created_at":"2026-02-20T16:00:54.870Z","updated_at":"2026-03-12T08:49:53.945Z","avatar_url":"https://github.com/aipartnerup.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/aipartnerup/apcore/main/apcore-logo.svg\" alt=\"apcore logo\" width=\"200\"/\u003e\n\u003c/div\u003e\n\n# apcore\n\n**AI-Perceivable Core**\n\n\u003e **Build once, invoke by Code or AI.**\n\nA schema-enforced module standard for the AI-Perceivable era.\n\napcore is an AI-Perceivable module standard that makes every interface naturally perceivable and understandable by AI through enforced Schema definitions and behavioral annotations. It provides schema validation, access control, middleware pipelines, and observability built in.\n\n## Features\n\n- **Schema-driven modules** — Define input/output schemas with TypeBox for runtime validation\n- **Executor pipeline** — Secured execution lifecycle: context → safety checks → lookup → ACL → approval gate → validation → middleware before → execute → output validation → middleware after → return\n- **Registry system** — File-based module discovery with metadata, dependencies, and topological ordering\n- **Binding loader** — YAML-based module registration for no-code integration\n- **Access control (ACL)** — Pattern-based rules with identity types, roles, and call-depth conditions\n- **Approval system** — Pluggable approval gate in the executor pipeline with sync and async (polling) flows, built-in handlers, and tracing integration\n- **Middleware** — Onion-model middleware with before/after/onError hooks and error recovery\n- **Observability** — Tracing (spans + exporters), metrics (counters + histograms + Prometheus export), structured logging with redaction\n- **Schema export** — JSON/YAML schema export with strict and compact modes\n- **Caching \u0026 pagination annotations** — `cacheable`, `cacheTtl`, `cacheKeyFields` for result caching; `paginated`, `paginationStyle` for paginated modules\n\n## Documentation\n\nFor full documentation, including Quick Start guides and API reference, visit:\n**[https://aipartnerup.github.io/apcore/getting-started.html](https://aipartnerup.github.io/apcore/getting-started.html)**\n\n## Requirements\n\n- Node.js \u003e= 18.0.0\n- TypeScript \u003e= 5.5\n\n## Installation\n\n```bash\nnpm install apcore-js\n```\n\n## Quick Start\n\n### Simplified Client (Recommended)\n\nThe `APCore` client provides a unified entry point that manages Registry and Executor for you:\n\n```typescript\nimport { Type } from '@sinclair/typebox';\nimport { APCore } from 'apcore-js';\n\nconst client = new APCore();\n\n// Register a module\nclient.module({\n  id: 'math.add',\n  description: 'Add two numbers',\n  inputSchema: Type.Object({ a: Type.Number(), b: Type.Number() }),\n  outputSchema: Type.Object({ sum: Type.Number() }),\n  execute: (inputs) =\u003e ({ sum: (inputs.a as number) + (inputs.b as number) }),\n});\n\n// Call, validate, stream — all from one client\nconst result = await client.call('math.add', { a: 10, b: 5 });\n// =\u003e { sum: 15 }\n\nconst preflight = client.validate('math.add', { a: 10, b: 5 });\n// =\u003e { valid: true, checks: [...], requiresApproval: false, errors: [] }\n```\n\n### Advanced: Manual Registry + Executor\n\n```typescript\nimport { Type } from '@sinclair/typebox';\nimport { FunctionModule, Registry, Executor } from 'apcore-js';\n\nconst greet = new FunctionModule({\n  execute: (inputs) =\u003e ({ greeting: `Hello, ${inputs.name}!` }),\n  moduleId: 'example.greet',\n  inputSchema: Type.Object({ name: Type.String() }),\n  outputSchema: Type.Object({ greeting: Type.String() }),\n  description: 'Greet a user',\n});\n\nconst registry = new Registry();\nregistry.register('example.greet', greet);\n\nconst executor = new Executor({ registry });\nconst result = await executor.call('example.greet', { name: 'World' });\n// =\u003e { greeting: 'Hello, World!' }\n```\n\n## API Overview\n\n| Class | Description |\n|-------|-------------|\n| `APCore` | High-level client — register modules, call, stream, validate |\n| `Registry` | Module storage — discover, register, get, list, watch |\n| `Executor` | Execution engine — call with middleware pipeline, ACL, approval |\n| `Context` | Request context — trace ID, identity, call chain, cancel token |\n| `Config` | Configuration — load from YAML, get/set values |\n| `ACL` | Access control — rule-based caller/target authorization |\n| `Middleware` | Pipeline hooks — before/after/onError interception |\n| `EventEmitter` | Event system — subscribe, emit, flush |\n\n## Examples\n\nThe `examples/` directory contains runnable examples demonstrating key features:\n\n| Example | Description |\n|---------|-------------|\n| `simple-client.ts` | APCore client with module registration and calls |\n| `modules/greet.ts` | Minimal FunctionModule |\n| `modules/get-user.ts` | Readonly + idempotent annotations |\n| `modules/send-email.ts` | Full-featured: annotations, examples, metadata, ContextLogger |\n| `modules/decorated-add.ts` | `module()` function for creating modules |\n| `bindings/format-date/` | YAML binding with target function |\n\n## Architecture\n\n```\nsrc/\n  index.ts              # Public API exports\n  client.ts             # High-level APCore client (unified entry point)\n  executor.ts           # Secured execution lifecycle\n  context.ts            # Execution context and identity\n  config.ts             # Dot-path configuration accessor\n  acl.ts                # Access control with pattern matching\n  approval.ts           # Pluggable approval gate (handlers, request/result types)\n  async-task.ts         # Async task manager\n  cancel.ts             # Cancellation token support\n  decorator.ts          # FunctionModule class and helpers\n  bindings.ts           # YAML binding loader\n  errors.ts             # Error hierarchy (36 typed errors)\n  error-code-registry.ts # Custom error code registration with collision detection\n  extensions.ts         # Extension manager\n  module.ts             # Module types and annotations\n  trace-context.ts      # W3C trace context (inject/extract)\n  version.ts            # Version negotiation (semver parsing)\n  events/\n    index.ts            # Event module barrel exports\n    emitter.ts          # Global event bus with fan-out delivery\n    subscribers.ts      # Webhook and A2A protocol event subscribers\n  middleware/\n    index.ts            # Middleware barrel exports\n    base.ts             # Middleware base class\n    manager.ts          # MiddlewareManager (onion model)\n    adapters.ts         # BeforeMiddleware, AfterMiddleware adapters\n    logging.ts          # LoggingMiddleware\n    retry.ts            # RetryMiddleware for automatic retry of retryable errors\n    error-history.ts    # Middleware that records errors into ErrorHistory\n    platform-notify.ts  # Threshold sensor with hysteresis for error/latency alerts\n  registry/\n    index.ts            # Registry barrel exports\n    registry.ts         # Registry with discover() pipeline\n    scanner.ts          # File-based module discovery\n    entry-point.ts      # Dynamic import and entry point resolution\n    metadata.ts         # YAML metadata and ID map loading\n    dependencies.ts     # Topological sort with cycle detection\n    validation.ts       # Module duck-type validation\n    schema-export.ts    # Schema export (JSON/YAML, strict/compact)\n    types.ts            # Registry type definitions\n  schema/\n    index.ts            # Schema barrel exports\n    loader.ts           # JSON Schema to TypeBox conversion\n    validator.ts        # Schema validation\n    exporter.ts         # Schema serialization\n    ref-resolver.ts     # $ref resolution\n    strict.ts           # Strict schema transforms\n    types.ts            # Schema type definitions\n    annotations.ts      # Annotation conflict resolution (YAML + code metadata)\n  observability/\n    index.ts            # Observability barrel exports\n    tracing.ts          # Span, SpanExporter, TracingMiddleware\n    metrics.ts          # MetricsCollector, MetricsMiddleware\n    metrics-utils.ts    # Shared metric extraction utilities\n    context-logger.ts   # ContextLogger, ObsLoggingMiddleware\n    usage.ts            # Time-windowed usage tracking with analytics\n    error-history.ts    # Error history with ring-buffer eviction and dedup\n  sys-modules/\n    index.ts            # System module barrel exports\n    registration.ts     # Auto-registration of sys.* modules and middleware\n    control.ts          # Runtime config update and hot-reload modules\n    health.ts           # System and per-module health modules\n    manifest.ts         # Module metadata and system manifest modules\n    toggle.ts           # Module disable/enable without unloading\n    usage.ts            # Usage summary and per-module usage detail modules\n  utils/\n    index.ts            # Utils barrel exports\n    pattern.ts          # Glob-style pattern matching\n    call-chain.ts       # Call chain safety guard (depth, frequency, cycles)\n    error-propagation.ts # Standardized error wrapping\n    normalize.ts        # Cross-language module ID normalization\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Type check\nnpm run typecheck\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Build\nnpm run build\n```\n\n## Testing\n\n- Core executor pipeline\n- Schema validation (strict mode, type coercion)\n- Middleware chain (ordering, transforms, error recovery)\n- ACL enforcement (patterns, conditions, identity types)\n- Registry system (scanner, metadata, entry points, dependencies)\n- Binding loader (YAML loading, target resolution, schema modes)\n- Observability (tracing, metrics, structured logging)\n- Integration tests (end-to-end flows, error propagation, safety checks)\n\n## Links\n\n- **Documentation:** [https://aipartnerup.github.io/apcore/getting-started.html](https://aipartnerup.github.io/apcore/getting-started.html)\n- **Specification:** [https://github.com/aipartnerup/apcore](https://github.com/aipartnerup/apcore)\n- **GitHub:** [https://github.com/aipartnerup/apcore-typescript](https://github.com/aipartnerup/apcore-typescript)\n- **npm:** [https://www.npmjs.com/package/apcore](https://www.npmjs.com/package/apcore)\n- **Issues:** [https://github.com/aipartnerup/apcore-typescript/issues](https://github.com/aipartnerup/apcore-typescript/issues)\n\n## License\n\nApache-2.0\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faipartnerup%2Fapcore-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faipartnerup%2Fapcore-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faipartnerup%2Fapcore-typescript/lists"}