Aegis SDK for JavaScript/TypeScript

Prerequisites

• Axis tenant account and active session from https://axis.velikey.com/auth/signin.
• Node.js 18+ and npm.
• Set either AXIS_SESSION_COOKIE or AXIS_SESSION_TOKEN before live calls (or use AXIS_AUTH_EMAIL/AXIS_AUTH_PASSWORD for harness bootstrap).
• Tenant policy already present in Axis (SDK policy mutation helpers are intentionally disabled for this API surface).

# manual-only example
export AXIS_BASE_URL="${AXIS_BASE_URL:-https://axis.velikey.com}"
export AXIS_SESSION_COOKIE="next-auth.session-token=REDACTED"
export AXIS_SESSION_TOKEN="REDACTED"
node --version
npm --version

Install + Minimal Example

# executable example
npm install github:sgreysond/velikey-js-sdk#v0.2.1

import { VeliKeySDK } from '@velikey/sdk';

const sdk = new VeliKeySDK({
  baseUrl: process.env.AXIS_BASE_URL || 'https://axis.velikey.com',
  sessionCookie: process.env.AXIS_SESSION_COOKIE,
  sessionToken: process.env.AXIS_SESSION_TOKEN,
  useSecureSessionCookie: true,
});

const health = await sdk.getHealth();
const policies = await sdk.policies.list({ isActive: true });
console.log({ health: health.status, activePolicies: policies.length });

Production Example (timeouts + retries)

import { VeliKeySDK } from '@velikey/sdk';

const sdk = new VeliKeySDK({
  baseUrl: process.env.AXIS_BASE_URL || 'https://axis.velikey.com',
  sessionCookie: process.env.AXIS_SESSION_COOKIE,
  sessionToken: process.env.AXIS_SESSION_TOKEN,
  useSecureSessionCookie: true,
  timeout: 20000,
  maxRetries: 2,
  retryMinDelayMs: 250,
  retryMaxDelayMs: 2000,
});

const usageSummary = await sdk.getUsageSummary();
console.log('estimated total USD:', usageSummary.costs.totalUsd);

Canary Rollout + Rollback

1. Select a tenant policy from GET /api/policies.
2. Plan rollout with a bounded canary.
3. Apply in dry-run first, then run non-dry-run with explicit confirmation.
4. If needed, rollback using the returned rollback token.

const policies = await sdk.policies.list({ isActive: true });
const policyId = policies[0]?.id;
if (!policyId) throw new Error('No active policy found');

const plan = await sdk.rollouts.plan({
  policyId,
  canaryPercent: 5,
  stabilizationWindowS: 300,
  explain: true,
});

const planId = plan.data?.plan_id;
if (!planId) throw new Error('plan_id missing');

const dryRunApply = await sdk.rollouts.apply({ planId, dryRun: true });
console.log('dry-run apply:', dryRunApply.success);

// Non-dry-run apply auto-sets confirm=true + confirmation=\"APPLY\".
const apply = await sdk.rollouts.apply({ planId, dryRun: false });
const rollbackToken = apply.data?.rollback_token;

if (rollbackToken) {
  // rollback auto-sets confirm=true + confirmation=\"ROLLBACK\".
  await sdk.rollouts.rollback({ rollbackToken });
}

Telemetry + Metering Readback

const before = await sdk.getUsageSummary();

await sdk.telemetry.ingest({
  event: 'docs.js_sdk.sample',
  properties: { source: 'docs', lane: 'js' },
});

const after = await sdk.getUsageSummary();
const telemetryDelta = after.usage.telemetryDataGB - before.usage.telemetryDataGB;
const costDelta = after.costs.totalUsd - before.costs.totalUsd;

console.log({ telemetryDelta, costDelta });

Troubleshooting

• 401 Unauthorized: session cookie/token missing or expired; re-authenticate at https://axis.velikey.com/auth/signin.
• Harness bootstrap fallback: if no cookie/token is pre-provisioned, set AXIS_AUTH_EMAIL and AXIS_AUTH_PASSWORD to attempt session bootstrap.
• axis_auth_schema_mismatch: hosted credentials callback returned a schema error; use a pre-provisioned valid session cookie/token until hosted auth deployment is corrected.
• 400 Confirmation required on apply/rollback: ensure you are using SDK methods (they auto-apply confirmation for non-dry-run actions).
• 429/5xx: SDK retries transient failures by default; check tenant limits and Axis status.
• No active policy: create/activate policy in Axis UI first, then rerun rollout flow.
• E_EVIDENCE_ROOT_MISMATCH in aggregate receipts: re-run with latest C8 lane scripts so summary artifacts and diagnostics are lane-relative.

Security Notes

• Do not log raw session cookies or bearer/API keys.
• Keep TLS verification enabled; do not set insecure HTTPS agents.
• Use least-privilege tenant credentials for automation runners.
• Persist rollout receipt IDs from apply/rollback responses for audit evidence.

Navigate Docs

Docs Index • Policy APIs • Rollout and rollback semantics • Troubleshooting