Skip to content

AGENTS.md

Latest commit

 

History

History
42 lines (30 loc) · 1.67 KB

AGENTS.md

File metadata and controls

42 lines (30 loc) · 1.67 KB
Raw

solid-webhook

Commands

npm run build      # Compile TypeScript to dist/src/
npm run typecheck  # TypeScript check (no emit)
npm start          # Run server (requires .env with all required vars)
npm run dev        # build + start
npm test           # Watch mode (vitest)
npm run test:run   # Single run

Required Environment Variables

  • WEBID - Solid WebID
  • ISSUER - OIDC issuer
  • WHITELISTED_ISSUERS - Comma-separated issuers; enforced in solidAuth.ts (403 if token iss not in list)
  • WEBHOOK_CONFIG_URL - URL to load RDF webhook config from
  • HANDLER_BASE_URL - Base URL for handler namespace (e.g., https://example.com/handlers#)

Build Output

TypeScript compiles to dist/src/ (not dist/). The entry point is dist/src/main.js.

TDD Approach

Tests live alongside source in tests/ directory, mirroring src/ structure. Run npm test for watch mode, npm run test:run for CI.

Key Files

  • src/main.ts - CLI entry point, startup sequence: createApp → startServer → createSolidFetch → fetch config → subscribe
  • src/index.ts - Server utilities: createApp, startServer, subscribeAll, unsubscribeAll
  • src/config.ts - loadConfig() reads all env vars, parseWebhooksFromRDF() parses Turtle RDF
  • src/middleware/solidAuth.ts - DPoP auth middleware; enforces whitelistedIssuers (403 if token iss not in list)
  • src/services/webhookChannel.ts - WebhookChannel2023 subscribe/unsubscribe

Testing Notes

  • Mock @soid/koa to avoid real network calls in tests
  • n3 Parser.parse() returns array synchronously, but callback mode is used for Store.addQuad()
  • Config tests use vi.resetModules() to reload env vars between tests