npm package: @primethoughts/credence-sdk
Description: TypeScript SDK for Credence Trust OS — typed client for 82+ gateway endpoints covering W3C VCs, OID4VCI/OID4VP, DIDComm, Trust Registry, and DPP lifecycle
Author: PrimeThoughts Innovation Pvt. Ltd.
Latest version: 1.0.0-rc.1

# @primethoughts/credence-sdk

TypeScript SDK for Credence Trust OS. Wraps all 82 gateway REST endpoints across 8 service modules.

## Installation

```bash
npm install @primethoughts/credence-sdk
```

Requires Node.js >= 20.0.0.

## Quick Start

```typescript
import { CredenceClient } from '@primethoughts/credence-sdk';

// Register a new supplier (public — no JWT required)
const credence = new CredenceClient({
  baseUrl: 'https://gateway.credence.example:8080',
});

const auth = await credence.identity.register({
  name: 'Jane Doe',
  email: 'jane@example.com',
  password: 'Secret123!',
  role: 'SUPPLIER',
});
credence.setToken(auth.token); // all subsequent calls authenticated

// Or login with existing credentials
const loginAuth = await credence.identity.login({
  email: 'jane@example.com',
  password: 'Secret123!',
});
credence.setToken(loginAuth.token);

// Identity — tenant management
const tenant = await credence.identity.createTenant({ name: 'Acme Corp' });
const tenants = await credence.identity.listTenants();

// Messaging — accept an invitation from DIA authority
const connection = await credence.messaging.acceptInvitation({
  invitationUrl: 'https://agent.example.com?oob=eyJhbGciOiJFZERTQSJ9',
  alias: 'dia-authority',
});

// Credentials
const credential = await credence.credentials.issue({ schemaId, subjectDid, claims });
const result = await credence.credentials.verifyV2({ presentationId, policyId });

// Registry (TRQP read)
const frameworks = await credence.registry.listFrameworks();

// Registry (admin write)
const framework = await credence.registry.admin.createFramework({ did, name, version });

// VDR
const schema = await credence.vdr.writeSchema({ name, version, attributes });
```

## Modules

| Module | Description | Endpoint Prefix |
|--------|------------|----------------|
| `identity` | Auth (register, login, password reset, refresh), tenants, DIDs, wallets | `/api/v1/auth/**`, `/api/v1/tenants/**` |
| `messaging` | Connections, create/accept invitations | `/api/v1/connections/**` |
| `credentials` | Issue, verify, revoke | `/api/v1/credentials/**` |
| `presentations` | Presentation exchange, OID4VP | `/api/v1/presentations/**` |
| `registry` | TRQP queries + admin write | `/api/v1/registry/**`, `/api/v1/admin/**` |
| `compliance` | Checks, audit events, rules | `/api/v1/compliance/**` |
| `evidence` | Upload, verify, link | `/api/v1/evidence/**` |
| `vdr` | Schemas, cred-defs, NYMs, revocation | `/api/vdr/**` |

## Features

- **Zero runtime dependencies** — uses only Node.js builtins (`node:crypto`)
- **Dual ESM + CJS build** — works in all Node.js environments
- **Full TypeScript types** — mirrored from Credence backend DTOs
- **Auto correlation ID** — `X-Correlation-ID` header on every request
- **Retry with backoff** — configurable retry for 429/502/503/504
- **RFC 7807 errors** — structured error responses with `CredenceApiError`
- **DID validation** — client-side allowlist check (did:key, did:peer, did:indy, did:web)
- **Key material detection** — prevents accidental secret leakage

## Configuration

```typescript
const credence = new CredenceClient({
  baseUrl: 'https://gateway:8080',
  auth: { type: 'jwt', token: 'eyJ...' },
  retry: { maxRetries: 3, baseDelay: 1000, maxDelay: 30000 },
  timeout: 30000,
  correlationId: 'custom-correlation-id', // optional; auto-generated if omitted
});

// Refresh token
credence.setToken(newToken);

// Add interceptors
credence.addRequestInterceptor(async (url, init) => {
  // modify request before sending
  return init;
});
```

## Breaking Changes (v0.2.0)

### Governance VC lifecycle methods now require `LifecycleTransitionRequest`

All 5 governance VC lifecycle methods (`submitForReview`, `activateGovernanceVc`, `suspendGovernanceVc`, `reinstateGovernanceVc`, `revokeGovernanceVc`) now require a `LifecycleTransitionRequest` body with a mandatory `actorDid` field:

```typescript
// Before (v0.1.x) — no longer works
await credence.registry.admin.submitForReview(vcId);

// After (v0.2.0) — actorDid is required
await credence.registry.admin.submitForReview(vcId, {
  actorDid: 'did:web:steward.example.com',
  reason: 'Ready for governance board review', // optional
});
```

### `GovernanceVcCreateRequest` now requires `proofHash`

The `proofHash` field (SHA-256 hash of canonical VC JSON) is now required when creating governance VCs for deduplication:

```typescript
await credence.registry.admin.createGovernanceVc({
  frameworkId: '...',
  vcType: 'ISSUER_AUTHORIZATION',
  vcJson: { /* W3C VCDM 2.0 */ },
  issuerDid: 'did:web:authority.example.com',
  subjectDid: 'did:web:issuer.example.com',
  validFrom: '2026-01-01T00:00:00Z',
  proofHash: 'sha256-hex-hash-of-canonical-vc-json', // now required
});
```

### Framework request field renames

`TrustFrameworkCreateRequest` and `TrustFrameworkUpdateRequest` use `did` (not `governingAuthority`) and `metadata` (not `description`):

```typescript
await credence.registry.admin.createFramework({
  did: 'did:web:authority.example.com',  // was: governingAuthority
  name: 'My Framework',
  version: '1.0.0',
  metadata: { description: '...' },       // was: description (string)
});
```

## Development

```bash
npm install          # Install dependencies
npm run build        # Build ESM + CJS + DTS
npm test             # Run 152 unit tests
npm run typecheck    # TypeScript type checking
```

## Spec & Compliance

- Spec: `specs/credence-sdk/spec.md` (85 FRs, 8 NFRs)
- Compliance audit: `specs/credence-sdk/compliance-audit.md` — all PASS
- KB references: `[KB:00-system]`, `[KB:01-architecture]`, `[KB:14-learnings-v1-v2]`