@zysec-ai/cpod-sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to `@zysec-ai/cpod-sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-06-11
+
+### Breaking Changes
+
+#### Domain Renames
+
+All 8 bare domain names have been renamed to qualified forms for clarity and EDM consistency:
+
+| Old Path | New Path |
+|----------|----------|
+| `technology/` | `technology.assets/` |
+| `assets/` | `assets.items/` |
+| `relationships/` | `relationships.edges/` |
+| `vulnerabilities/` | `vulnerabilities.items/` |
+| `cloud-resources/` | `cloud-resources.items/` |
+| `entitlements/` | `entitlements.items/` |
+| `licenses/` | `licenses.items/` |
+| `audit/` | `audit.records/` |
+
+#### Import Path Updates
+
+All imports from renamed domains must use qualified paths:
+
+```typescript
+// Before (v1.x)
+import { TechnologyService } from '@zysec-ai/cpod-sdk/dist/technology/service.js';
+import { AssetService } from '@zysec-ai/cpod-sdk/dist/assets/service.js';
+
+// After (v2.0.0)
+import { TechnologyService } from '@zysec-ai/cpod-sdk/dist/technology.assets/service.js';
+import { AssetService } from '@zysec-ai/cpod-sdk/dist/assets.items/service.js';
+```
+
+#### Client Namespace Property Changes
+
+All client namespace properties have been renamed to match qualified domain names:
+
+| Old Property | New Property |
+|--------------|--------------|
+| `client.technology` | `client.technologyAssets` |
+| `client.assets` | `client.assetsItems` |
+| `client.relationships` | `client.relationshipsEdges` |
+| `client.vulnerabilities` | `client.vulnerabilitiesItems` |
+| `client.cloudResources` | `client.cloudResourcesItems` |
+| `client.entitlements` | `client.entitlementsItems` |
+| `client.licenses` | `client.licensesItems` |
+| `client.audit` | `client.auditRecords` |
+
+#### MCP Domain Updates
+
+MCP tool domains now use qualified names:
+
+- `'technology'` → `'technology.assets'`
+- `'assets'` → `'assets.items'`
+- `'relationships'` → `'relationships.edges'`
+- `'vulnerabilities'` → `'vulnerabilities.items'`
+- `'cloudResources'` → `'cloudResources.items'`
+- `'entitlements'` → `'entitlements.items'`
+- `'licenses'` → `'licenses.items'`
+
+### Migration
+
+See [docs/MIGRATION_v2.md](../../docs/MIGRATION_v2.md) for detailed migration guide, codemod suggestions, and rollback instructions.
+
+### Added
+
+- Domain naming linter (`scripts/lint-domain-naming.mjs`) to enforce qualified domain names
+- Comprehensive migration guide with codemod examples
+- Breaking change documentation
+
+### Changed
+
+- All domain folders now use qualified names following EDM conventions
+- Client namespace properties renamed for consistency
+- MCP manifest domains use qualified names
+
+## [1.0.0] - 2026-05-20
+
+### Added
+- Initial release of the cPod TypeScript/JavaScript SDK
+- `CpodClient` main client class with configurable API key, base URL, and timeout
+- `PodService` with full CRUD operations (`list`, `get`, `create`, `update`, `delete`)
+- `EventService` with `subscribe` (EventEmitter pattern) and `getHistory`
+- `TenantService` with full CRUD operations
+- `HttpClient` with automatic retry (3 attempts, exponential backoff), auth header injection, and timeout support
+- Typed error hierarchy: `CpodError`, `ApiError`, `AuthenticationError`, `NotFoundError`, `RateLimitError`
+- Full TypeScript declarations and source maps
+- ESM and CJS dual build output
+- Tree-shakeable subpath exports (`@zysec-ai/cpod-sdk/pods`, `@zysec-ai/cpod-sdk/events`)

package/README.md

@@ -0,0 +1,315 @@
+# @zysec-ai/cpod-sdk — TypeScript / JavaScript SDK
+
+Official TypeScript SDK for the cPod Enterprise Data Model (EDM). Typed access to 60+ service namespaces covering people, technology, licenses, assets, risk & compliance, CRM, finance, HR, legal, marketing, customer success, process optimization, surveys, external integrations, and all cPod platform surfaces.
+
+## Install
+
+```bash
+npm install @zysec-ai/cpod-sdk
+# or
+pnpm add @zysec-ai/cpod-sdk
+# or
+yarn add @zysec-ai/cpod-sdk
+```
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5+ recommended
+- A cPod backend URL and credentials (API key or OIDC token)
+
+## Quick Start
+
+```ts
+import { CpodClient } from '@zysec-ai/cpod-sdk'
+
+const cpod = new CpodClient({ apiKey: 'sk-...' })
+
+const people = await cpod.people.persons.list({ pageSize: 10 })
+const accounts = await cpod.customer.accounts.list({ pageSize: 10 })
+const projects = await cpod.projects.project.list({ pageSize: 10 })
+
+console.log({
+  people: people.items.length,
+  accounts: accounts.items.length,
+  projects: projects.items.length,
+})
+```
+
+## Authentication Modes
+
+### API Key (service account / emulator)
+
+```ts
+const cpod = new CpodClient({
+  apiKey: process.env.CPOD_API_KEY!,
+  baseUrl: process.env.CPOD_API_URL ?? 'https://api.cyberpod.app',
+  appId: process.env.CPOD_APP_ID,
+})
+```
+
+### Environment-based (zero-config)
+
+```ts
+const cpod = CpodClient.fromEnv()
+```
+
+Reads `CPOD_API_KEY` (required), `CPOD_API_URL` / `CPOD_BASE_URL`, and `CPOD_APP_ID` from the environment.
+
+### Token-based (user-scoped, zero app secret)
+
+```ts
+const cpod = CpodClient.fromToken(accessToken, {
+  refreshToken,
+  baseUrl: process.env.CPOD_API_URL,
+  appId: process.env.CPOD_APP_ID,
+})
+
+const me = await cpod.auth.me()
+```
+
+### Browser popup login
+
+```ts
+const cpod = await CpodClient.login({ backendUrl: 'https://api.cyberpod.app' })
+```
+
+### Redirect login
+
+```ts
+const { loginUrl } = CpodClient.beginLogin({
+  backendUrl: 'https://api.cyberpod.app',
+  returnTo: `${location.origin}/auth/callback`,
+})
+// redirect user, then on callback:
+const { accessToken, refreshToken } = await CpodClient.exchangeCode({ backendUrl, code })
+const cpod = CpodClient.fromToken(accessToken, { refreshToken })
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `CPOD_API_KEY` | Yes (API key mode) | — | Service-account API key or emulator dev-token |
+| `CPOD_API_URL` | No | `https://api.cyberpod.app` | Backend base URL. Takes precedence over `CPOD_BASE_URL` |
+| `CPOD_BASE_URL` | No | `https://api.cyberpod.app` | Alias for `CPOD_API_URL` (fallback) |
+| `CPOD_APP_ID` | For MCP/registry | — | App identifier for MCP tool registration and app storage scoping |
+
+## Service Index
+
+The SDK exposes 60+ top-level namespaces. All are available on every `CpodClient` instance.
+
+### Business EDM Domains
+
+| Namespace | Sub-services | Description |
+|---|---|---|
+| `people` | `persons`, `groups` | Person and Group records |
+| `groups` | — | Group records (alias of `people.groups`) |
+| `technology` | — | TechnologyAsset records |
+| `entitlements` | — | AccessEntitlement grants |
+| `licenses` | — | SoftwareLicense and LicenseAssignment |
+| `assets` | — | PhysicalAsset records |
+| `risk` | — | RiskItem records |
+| `vulnerabilities` | — | CVE / finding records with severity scoring |
+| `complianceControls` | — | SOC 2, ISO 27001, PCI, HIPAA, NIST controls |
+| `cloudResources` | — | AWS / GCP / Azure / OCI resources |
+| `relationships` | — | EDM graph relationship traversal |
+| `dataSources` | — | External data source integrations |
+| `contracts` | `vendors`, `contract`, `obligations` | Vendor, Contract, ContractObligation |
+| `work` | `timeEntries`, `comments`, `capacity` | Time tracking, comments, capacity planning |
+| `investments` | `portfolio`, `costCenters` | Technology investment portfolio, cost centers |
+| `performance` | `reviews`, `goals`, `learningRecords` | Performance reviews, goals, learning records |
+| `employee` | `skills`, `calendarEvents`, `leaveRequests`, `meetingNotes` | Employee experience |
+| `okr` | `objectives`, `keyResults` | OKR management |
+| `projects` | `project`, `tasks`, `sprints`, `features` | Project management |
+| `customer` | `accounts`, `contacts`, `deals`, `activities`, `quotes`, `lineItems` | CRM |
+| `grc` | `frameworks`, `controls`, `evidence`, `incidents`, `risks` | Governance, Risk & Compliance |
+| `soc` | `alerts`, `investigations`, `playbooks` | Security Operations Center |
+| `learning` | `cohorts`, `assessments` | Learning management |
+| `rfp` | `records`, `questions`, `responses` | RFP management |
+| `knowledge` | `documents`, `chunks`, `entities`, `templates`, `sops` | Knowledge base |
+| `integration` | `applications`, `connectors`, `apiKeys`, `webhooks` | Integration platform |
+| `helpdesk` | `tickets`, `slaPolicies` | Helpdesk / support tickets |
+| `hr` | `jobPostings`, `applicants`, `onboardingTasks`, `offboardingTasks` | HR lifecycle |
+| `notifications` | `notification`, `announcements` | Notifications and announcements |
+| `approvals` | `requests`, `steps` | Approval workflows |
+| `finance` | `invoices`, `purchaseOrders`, `expenses`, `budgets`, `budgetLines` | Finance |
+| `policies` | `policy`, `acknowledgements`, `reviews` | Policy management |
+| `org` | `locations`, `departments` | Organizational structure |
+| `catalog` | `products`, `categories` | Product catalog |
+| `procurement` | `suppliers` | Procurement / suppliers |
+| `operations` | `accessRequests`, `hrRequests`, `pending`, `equipment`, `travel` | Cross-functional request workflows |
+| `vendor` | `scorecards`, `insurance`, `certifications`, `contacts`, `onboarding` | Vendor management |
+| `marketing` | `campaigns`, `leads`, `content`, `events`, `social`, `emails`, `analytics` | Marketing |
+| `legal` | `contracts`, `ndas`, `cases`, `ip`, `compliance`, `reviews` | Legal |
+| `clientops` | `healthScores`, `playbooks`, `onboardingPlans`, `retentionRisks`, `expansions` | Customer success and retention |
+| `integrations` | `connections`, `dataSources`, `syncState` | External system connectivity and sync |
+| `process` | `maps`, `bottlenecks`, `efficiencyScores` | Business process optimization |
+| `surveys` | `surveys`, `responses`, `analytics` | Feedback collection and analysis |
+| `completions` | `chat` | OpenAI-compatible completions gateway |
+
+### Platform Surfaces
+
+| Namespace | Sub-services | Description |
+|---|---|---|
+| `storage` | `files`, `db`, `kv`, `objects`, `records`, `sqlite` | App-private sandboxed storage |
+| `skills` | — | Platform skill listing and execution |
+| `workflows` | — | Workflow management and triggering |
+| `jobs` | — | Async job submission and monitoring |
+| `flags` | — | Feature flag evaluation |
+| `secrets` | — | Platform vault secret resolution |
+| `mcp` | — | MCP tool registration and proxy |
+| `registry` | — | Capability registry (app-tool discover/call) |
+| `telemetry` | `audit`, `traces`, `events` | Audit events, LLM traces, analytics events |
+| `audit` | — | Platform audit event emit/query |
+| `events` | — | Event subscription and history |
+| `analytics` | `dashboards`, `metrics`, `reports` | Dashboards, time-series metrics, reports |
+| `graph` | `nodes`, `edges`, `queries` | Knowledge graph operations |
+| `planner` | `dailyPlans`, `planItems` | User-scoped daily planning |
+| `postmortems` | `timeline` | Incident timeline tracking |
+| `masking` | — | PII and sensitive string masking |
+| `workspaces` | — | Personal and shared file/folder containers |
+| `apps` | — | App registration and MCP tool management |
+
+### Auth / Identity
+
+| Namespace | Sub-services | Description |
+|---|---|---|
+| `auth` | — | Login, refresh, validate, /auth/me, change-password, invites |
+| `organizations` | — | Organization context from JWT |
+| `pods` | — | Pod resource CRUD and lifecycle |
+| `credentials` | — | API keys and service account credentials |
+| `userProfiles` | — | User profile resources |
+| `agents` | — | Configured AI agents (model, skills, MCP, secrets) |
+| `mcpServers` | — | External MCP server integrations |
+| `memory` | — | Cognitive memory layer (facts, preferences, instructions) |
+| `chat` | — | Human-in-the-Loop approval for agent tool calls |
+| `tenants` | — | Tenant administration |
+
+## EDM CRUD Example
+
+```ts
+// List
+const people = await cpod.people.persons.list({ pageSize: 25 })
+
+// Create
+const account = await cpod.customer.accounts.create({
+  tenantId: 'tenant_dev',
+  appId: 'crm-lite',
+  ownerId: 'user_dev',
+  name: 'Acme Corp',
+  lifecycleStage: 'prospect',
+})
+
+// Update
+const updated = await cpod.customer.accounts.update(account.id, {
+  healthScore: 'green',
+})
+
+// Get
+const record = await cpod.customer.accounts.get(account.id)
+```
+
+## Storage
+
+App-private storage for preferences, drafts, pins, cache metadata, and small files. Sandbox-scoped to tenant + app + user automatically.
+
+```ts
+// Key-value
+await cpod.storage.kv.set('crm-lite:last-filter', { owner: 'me' })
+const value = await cpod.storage.kv.get('crm-lite:last-filter')
+
+// Files (MinIO-backed, presigned URLs)
+await cpod.storage.files.upload('report.pdf', blob)
+
+// Structured documents (MongoDB-backed)
+await cpod.storage.db.insert('drafts', { title: 'Q4 Plan', body: '...' })
+```
+
+## MCP Tools
+
+Register tools for agent-callable workflows. Tools are proxied through a single audited endpoint.
+
+```ts
+await cpod.mcp.register([
+  {
+    name: 'crm_lite_prepare_daily_brief',
+    description: 'Prepare a source-backed CRM follow-up brief.',
+    endpoint: '/api/mcp/crm_lite_prepare_daily_brief',
+    method: 'POST',
+    inputSchema: {
+      type: 'object',
+      properties: { focus: { type: 'string' } },
+    },
+    maskResponse: true,
+  },
+])
+```
+
+Auto-derive tools from every service's MCP manifest:
+
+```ts
+const tools = cpod.mcpTools() // → McpToolDefinition[]
+```
+
+## Registry
+
+Dynamic app-tool discover and call through the capability registry:
+
+```ts
+const tools = await cpod.registry.discover({ appId: 'my-app' })
+const result = await cpod.registry.call('my-app', 'tool_name', { arg: 'value' })
+```
+
+## Error Handling
+
+```ts
+import { AuthenticationError, NotFoundError, RateLimitError, ApiError } from '@zysec-ai/cpod-sdk'
+
+try {
+  await cpod.customer.accounts.get('missing-id')
+} catch (error) {
+  if (error instanceof NotFoundError) console.log('Record not found')
+  else if (error instanceof AuthenticationError) console.log('Bad or expired credentials')
+  else if (error instanceof RateLimitError) console.log('Rate limited')
+  else if (error instanceof ApiError) console.log(`API error: ${error.message}`)
+  else throw error
+}
+```
+
+## Escape Hatch
+
+Prefer typed services. For endpoints without a typed method yet:
+
+```ts
+const result = await cpod.request('GET', '/api/v1/customer/accounts')
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `CPOD_API_KEY environment variable is required` | Set `CPOD_API_KEY` or use `CpodClient.fromToken(...)` |
+| Calls go to production unexpectedly | Set `CPOD_API_URL=http://localhost:4000` for emulator/local backend |
+| Browser popup blocked | Call `CpodClient.login()` from a click handler or use `beginLogin()` redirect flow |
+| 401 after user login | Pass `refreshToken` to `fromToken()` so the SDK can refresh and retry |
+
+## Local Development
+
+```bash
+pnpm install
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+From the monorepo root:
+
+```bash
+pnpm --filter @zysec-ai/cpod-sdk build
+pnpm --filter @zysec-ai/cpod-sdk test
+```
+
+## License
+
+MIT

package/bin/.env.example

@@ -0,0 +1,21 @@
+# cpod-mcp-server environment template.
+#
+# The MCP server (bin/cpod-mcp-server.mjs) auto-loads a .env file from
+# either the current working directory or from this directory. Copy this
+# file to .env, fill it in, and the MCP host config only needs to pass
+# CPOD_API_KEY + CPOD_BASE_URL.
+#
+#   cp .env.example .env
+
+# ── Required ────────────────────────────────────────────────────────────────
+CPOD_API_KEY=eyJ...
+CPOD_BASE_URL=https://api.cpod.example
+
+# ── EDM / storage direct-mode (required for those tools to work) ────────────
+# Get the URI from your cpod admin or vault. Never commit a real one here.
+CPOD_MONGO_URI=mongodb://USER:PASS@HOST:27017/?authSource=admin
+CPOD_MONGO_DB=cpod-sdk
+
+# ── Optional ────────────────────────────────────────────────────────────────
+# CPOD_APP_ID=<app-id>          # multi-app tenant scoping
+# CPOD_TENANT_ID=<tenant-id>    # pin a tenant explicitly

package/bin/cpod-mcp-server.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// ─────────────────────────────────────────────────────────────────────────────
+// cpod-mcp-server — stdio MCP server that exposes every cpod-sdk method as
+// an MCP tool. Walks client.mcpTools() once at startup; adding a new SDK
+// method (with a manifest entry) auto-extends this server's tool list.
+//
+// Connects MCP hosts (Claude Desktop, Cursor, Continue, etc.) to the
+// entire cpod platform without per-tool wiring.
+//
+// MCP host config — only API_KEY + BASE_URL needed:
+//   {
+//     "mcpServers": {
+//       "cpod": {
+//         "command": "node",
+//         "args": ["./node_modules/@cpod/sdk/bin/cpod-mcp-server.mjs"],
+//         "env": {
+//           "CPOD_API_KEY":   "<your token>",
+//           "CPOD_BASE_URL":  "https://api.example.com"
+//         }
+//       }
+//     }
+//   }
+//
+// Server-side config — Mongo URI for direct-mode EDM, etc. live in a
+// `.env` file alongside the install or in the host process env. The
+// server auto-loads `.env` from the current working directory and from
+// the directory containing this script. Documented env vars:
+//
+//   CPOD_API_KEY      required — bearer token for backend calls
+//   CPOD_BASE_URL     required — cpod-backend URL
+//   CPOD_MONGO_URI    needed by EDM/storage direct-mode services
+//   CPOD_MONGO_DB     defaults to "cpod-sdk"
+//   CPOD_APP_ID       optional — multi-app tenant scoping
+//   CPOD_TENANT_ID    optional — pin a tenant explicitly
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { fileURLToPath } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { config as loadDotenv } from 'dotenv'
+
+// Load .env from the cwd first, then from the script's own dir so a
+// bundled install can ship its own defaults.
+loadDotenv()
+loadDotenv({ path: resolve(dirname(fileURLToPath(import.meta.url)), '.env') })
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+import { CpodClient, invokeTool } from '../dist/index.mjs'
+
+// ── Config from env ─────────────────────────────────────────────────────────
+const apiKey   = process.env.CPOD_API_KEY
+const baseUrl  = process.env.CPOD_BASE_URL || process.env.CPOD_BACKEND_URL
+const mongoUri = process.env.CPOD_MONGO_URI
+const mongoDb  = process.env.CPOD_MONGO_DB
+const appId    = process.env.CPOD_APP_ID
+const tenantId = process.env.CPOD_TENANT_ID
+
+if (!apiKey || !baseUrl) {
+  process.stderr.write(
+    'cpod-mcp-server: CPOD_API_KEY and CPOD_BASE_URL are required.\n' +
+    'Pass them via the MCP host\'s env block.\n',
+  )
+  process.exit(2)
+}
+
+const client = new CpodClient({
+  apiKey,
+  baseUrl,
+  ...(mongoUri ? { mongoUri }   : {}),
+  ...(mongoDb  ? { mongoDb }    : {}),
+  ...(appId    ? { appId }      : {}),
+  ...(tenantId ? { tenantId }   : {}),
+})
+
+const tools = client.mcpTools()
+process.stderr.write(`cpod-mcp-server: registered ${tools.length} tools.\n`)
+
+// ── MCP server wiring ───────────────────────────────────────────────────────
+const server = new Server(
+  {
+    name: 'cpod-sdk',
+    version: '1.0.0',
+  },
+  {
+    capabilities: { tools: {} },
+  },
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params
+  try {
+    const result = await invokeTool(client, name, args)
+    return {
+      content: [
+        {
+          type: 'text',
+          text: typeof result === 'string'
+            ? result
+            : JSON.stringify(result, null, 2),
+        },
+      ],
+    }
+  } catch (err) {
+    return {
+      isError: true,
+      content: [
+        {
+          type: 'text',
+          text: `Error: ${err?.message || String(err)}`,
+        },
+      ],
+    }
+  }
+})
+
+// ── Start ────────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport()
+await server.connect(transport)
+
+// Graceful shutdown — closes Mongo/MinIO connections cleanly.
+async function shutdown(signal) {
+  process.stderr.write(`cpod-mcp-server: received ${signal}, closing...\n`)
+  try { await client.mongo.close() } catch {}
+  process.exit(0)
+}
+process.on('SIGINT',  () => shutdown('SIGINT'))
+process.on('SIGTERM', () => shutdown('SIGTERM'))