@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

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

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)

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)

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)

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

const cpod = await CpodClient.login({ backendUrl: 'https://api.cyberpod.app' })

Redirect login

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

// 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.

// 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.

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:

const tools = cpod.mcpTools() // → McpToolDefinition[]

Registry

Dynamic app-tool discover and call through the capability registry:

const tools = await cpod.registry.discover({ appId: 'my-app' })
const result = await cpod.registry.call('my-app', 'tool_name', { arg: 'value' })

Error Handling

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:

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

pnpm install
pnpm build
pnpm typecheck
pnpm test

From the monorepo root:

pnpm --filter @zysec-ai/cpod-sdk build
pnpm --filter @zysec-ai/cpod-sdk test

License

MIT