@tally/sdk TypeScript Client Reference

import { createClient } from '@tally/sdk';

const client = createClient({
  baseUrl: 'https://api.example.com',
  token: 'your-jwt-token',  // optional; can also set per-call
});

// Unauthenticated liveness probe — GET /health
const { ok, service } = await client.health();

// Service metadata — GET /v1/meta
const meta = await client.meta();
console.log(meta.version, meta.gitSha, meta.env);

const current = await client.subjects.getCurrent(
  'entity',
  'ent_acme_001',
  { tenantId: 'my-org', verify: 'hash' }
);

console.log(current.identity);
console.log(current.current_snapshot.snapshot_version);

const snapshot = await client.subjects.getLatestSnapshot(
  'entity',
  'ent_acme_001',
  { tenantId: 'my-org', view: 'full' }
);

const v3 = await client.subjects.getSnapshotByVersion(
  'entity',
  'ent_acme_001',
  3,
  { tenantId: 'my-org', view: 'full' }
);

const snap = await client.subjects.getSnapshotById(
  'snap_01j9xk...',
  { tenantId: 'my-org', view: 'full' }
);

const proof = await client.subjects.getSnapshotProof('snap_01j9xk...', {
  tenantId: 'my-org',
});
console.log(proof.envelope_hash, proof.prev_hash);

const history = await client.subjects.listSnapshots(
  'entity',
  'ent_acme_001',
  { tenantId: 'my-org', limit: 20, order: 'desc', view: 'full' }
);

for (const snap of history.items) {
  console.log(snap.snapshot_version, snap.generated_at);
}

// Follow the cursor for the next page
if (history.page.next_cursor) {
  const next = await client.subjects.listSnapshots(
    'entity', 'ent_acme_001',
    { tenantId: 'my-org', cursor: history.page.next_cursor }
  );
}

const chain = await client.subjects.listChainProof(
  'entity',
  'ent_acme_001',
  { tenantId: 'my-org', order: 'asc' }
);

const exported = await client.subjects.export('entity', 'ent_acme_001', {
  tenantId: 'my-org',
});

// exported.snapshots contains every version with envelope + hash fields

const diff = await client.subjects.diffByVersion(
  'entity',
  'ent_acme_001',
  2,
  4,
  { tenantId: 'my-org', includeAttribution: 'changed_only' }
);

for (const op of diff.ops) {
  console.log(op.op, op.path, op.value);
}

const diff = await client.subjects.diffById(
  'snap_01j9xk_from',
  'snap_01j9xk_to',
  { tenantId: 'my-org' }
);

// Step 1 — Propose an RFC 6902 patch
const { update_id } = await client.updates.propose(
  {
    subject_id: 'ent_acme_001',
    base_snapshot_id: 'snap_01j9xk...',
    base_snapshot_version: 4,
    patch: [
      { op: 'replace', path: '/attributes/entity_status', value: 'inactive' },
    ],
    // optional idempotency key:
    request_id: 'req_my_unique_key',
    created_by: 'principal_abc',
  },
  { tenantId: 'my-org' }
);

// Step 2 — Apply the proposed update (produces a new snapshot version)
const result = await client.updates.apply(update_id, { tenantId: 'my-org' });

const result = await client.entityStates.create(
  {
    subject_type: 'entity',
    subject_id: 'ent_acme_001',
    attributes: {
      entity_status: 'active',
      legal_name: 'Acme Corporation',
      registration_country: 'US',
    },
  },
  { tenantId: 'my-org' }
);

const tenant = await client.tenants.create({
  tenant_id: 'my-org',
  tenant_type: 'subject_org',
  name: 'My Organisation',
  slug: 'my-org',   // optional
});

const usage = await client.tenants.getUsage('my-org', {
  from: '2024-01-01T00:00:00Z',
  to:   '2024-02-01T00:00:00Z',
});

await client.tenants.upsertMember('my-org', 'principal_xyz', 'editor');

await client.tenants.addOwner('my-org', 'entity', 'ent_acme_001', {
  owner_type: 'tenant',
  owner_id:   'my-org',
});

const { items } = await client.tenants.listOwners('my-org', 'entity', 'ent_acme_001');

const grant = await client.tenants.createGrant('my-org', {
  subject_type:      'entity',
  subject_id:        'ent_acme_001',
  grantee_tenant_id: 'counterparty-org',
  scopes:            ['read_latest', 'read_diff'],
  expires_at:        '2025-12-31T23:59:59Z',  // optional
});

const { items } = await client.tenants.listGrants('my-org', 'entity', 'ent_acme_001');

await client.tenants.revokeGrant('my-org', grant.grant_id);

const { items, page } = await client.tenants.listAccessibleSubjects('counterparty-org', {
  limit: 50,
});

for (const subject of items) {
  console.log(subject.subject_id, subject.scopes, subject.latest_snapshot?.snapshot_version);
}

// Counterparty creates the request
const { refresh_request } = await client.refreshRequests.create(
  'entity',
  'ent_acme_001',
  {
    requesting_tenant_id: 'counterparty-org',
    reason_code: 'periodic_review',
    message: 'Annual KYC refresh required.',
    requested_paths: ['/attributes/entity_status', '/attributes/legal_name'],
    expires_at: '2025-03-01T00:00:00Z',
  }
);

const requestId = refresh_request.refresh_request_id;

// Owner fetches the request
const { refresh_request: fetched } = await client.refreshRequests.get(
  'entity',
  'ent_acme_001',
  requestId
);

// Owner lists all pending requests for a subject
const { items } = await client.refreshRequests.list('entity', 'ent_acme_001');

// After publishing a new snapshot, the owner marks it fulfilled
const { refresh_request: resolved } = await client.refreshRequests.fulfill(
  'entity',
  'ent_acme_001',
  requestId,
  'snap_01jnew...'   // resolved_snapshot_id
);

console.log(resolved.status);  // 'fulfilled'

const { webhook_subscription, secret } = await client.webhooks.create({
  tenant_id:   'my-org',
  target_url:  'https://my-app.example.com/webhooks/tally',
  event_types: ['identity.snapshot.created', 'refresh_request.fulfilled'],
});

// ⚠️ Store `secret` immediately — it is returned only once and cannot be retrieved again.
// Use it to verify the HMAC signature on incoming webhook payloads.
console.log('Webhook ID:', webhook_subscription.subscription_id);
console.log('Secret:',     secret);

// List all subscriptions for a tenant
const { items } = await client.webhooks.list('my-org');

// Fetch a single subscription
const { webhook_subscription } = await client.webhooks.get(subscription_id);

// Update URL, status, or event types
const updated = await client.webhooks.update(subscription_id, {
  status:      'disabled',
  target_url:  'https://my-app.example.com/webhooks/tally-v2',
  event_types: ['identity.snapshot.created'],
});

// Rotate the HMAC secret (returns a new one-time secret)
const { secret: newSecret } = await client.webhooks.rotateSecret(subscription_id);

import { createClient } from '@tally/sdk';

const client = createClient({ baseUrl: 'https://api.example.com', token: 'my-token' });

try {
  const snapshot = await client.subjects.getLatestSnapshot('entity', 'ent_acme_001', {
    tenantId: 'my-org',
  });
  console.log(snapshot);
} catch (err) {
  if (err instanceof Error) {
    // Example: "HTTP 403 Forbidden: {"error":"insufficient_scope"}"
    console.error('Tally API error:', err.message);

    // Parse the status code if you need to branch on it
    const match = err.message.match(/^HTTP (\d+)/);
    const statusCode = match ? parseInt(match[1], 10) : null;

    if (statusCode === 401) {
      // Token expired or missing — re-authenticate
    } else if (statusCode === 403) {
      // Insufficient scope or role
    } else if (statusCode === 404) {
      // Subject or resource does not exist
    }
  }
}

import type {
  SubjectType,
  GrantScope,
  MemberRole,
  WebhookEventType,
  SnapshotFull,
  SnapshotHeader,
  DiffResponse,
  TenantRow,
  GrantRow,
  RefreshRequest,
  WebhookSubscription,
} from '@tally/sdk';