@aionis/sdk

TypeScript SDK for Aionis Memory Graph API.

Install

npm i @aionis/[email protected]

The package also exposes the local developer CLI:

npx @aionis/[email protected] --help

If you do not have a local Aionis repository, aionis dev can now bootstrap Lite by:

1. checking the local runtime cache
2. trying a versioned runtime bundle
3. falling back to a GitHub source archive bootstrap path

Usage

import { AionisClient } from "@aionis/sdk";

const client = new AionisClient({
  base_url: "http://localhost:3001",
  timeout_ms: 10000,
  retry: { max_retries: 2 },
  api_key: process.env.API_KEY,          // optional: X-Api-Key
  auth_bearer: process.env.AUTH_BEARER,  // optional: Authorization: Bearer <token>
  admin_token: process.env.ADMIN_TOKEN,  // optional: X-Admin-Token (debug/admin routes)
});

const out = await client.write({
  scope: "default",
  input_text: "sdk write",
  auto_embed: false,
  nodes: [{ client_id: "sdk_evt_1", type: "event", text_summary: "hello sdk" }],
  edges: [],
});

console.log(out.status, out.request_id, out.data.commit_id);

For Aionis Doc continuity and resume flows, the SDK also exposes a high-level helper:

const resumed = await client.docResume({
  recover_result,
  candidates: ["resume_patch", "request_review"],
  feedback_outcome: "positive",
});

console.log(resumed.resume_summary.resume_state);
console.log(resumed.resume_summary.lifecycle_transition);

If you only have a handoff anchor or recover request, use the wrapped flow:

const resumed = await client.docRecoverAndResume({
  recover_request: { anchor: "aionis-doc:workflow-001", scope: "default" },
  input_kind: "handoff-store-request",
  candidates: ["resume_patch", "request_review"],
});

Auth Options

1. api_key: sends X-Api-Key.
2. auth_bearer: sends Authorization: Bearer <token>.
3. admin_token: sends X-Admin-Token (mainly for debug/admin flows).

If you set custom headers manually, the SDK will not override existing auth headers.

Covered methods

1. write
2. recall
3. recallText
4. contextAssemble
5. planningContext
6. find
7. listSessions
8. createSession
9. writeEvent
10. listSessionEvents
11. packExport
12. packImport
13. archiveRehydrate
14. nodesActivate
15. handoffStore
16. handoffRecover
17. sandboxCreateSession
18. sandboxExecute
19. sandboxRunGet
20. sandboxRunLogs
21. sandboxRunArtifact
22. sandboxRunCancel
23. rulesEvaluate
24. rulesState
25. toolsSelect
26. toolsDecision
27. toolsRun
28. toolsFeedback
29. feedback
30. replayRunStart
31. replayStepBefore
32. replayStepAfter
33. replayRunEnd
34. replayRunGet
35. replayPlaybookCompileFromRun
36. replayPlaybookGet
37. replayPlaybookCandidate
38. replayPlaybookPromote
39. replayPlaybookRepair
40. replayPlaybookRepairReview
41. replayPlaybookRun
42. replayPlaybookDispatch
43. automationCreate
44. automationGet
45. automationList
46. automationTelemetry
47. automationAssignReviewer
48. automationPromote
49. automationValidate
50. automationGraphValidate
51. automationShadowReport
52. automationShadowReview
53. automationShadowValidate
54. automationShadowValidateDispatch
55. automationCompensationPolicyMatrix
56. automationRun
57. automationRunGet
58. automationRunList
59. automationRunAssignReviewer
60. automationRunCancel
61. automationRunApproveRepair
62. automationRunCompensationRetry
63. automationRunCompensationAssign
64. automationRunCompensationRecordAction
65. automationRunResume
66. automationRunRejectRepair
67. docRecover
68. docResume
69. docRecoverAndResume
70. health
71. getCapabilityContract

CLI Commands

The bundled Phase 1 developer CLI supports:

1. aionis dev
2. aionis stop
3. aionis health
4. aionis doctor
5. aionis selfcheck

Useful aionis dev flags:

1. --runtime-root /path/to/Aionis
2. --runtime-version 0.2.21
3. --runtime-cache-dir ~/.aionis/runtime
4. --force-download
5. --offline

Admin/control methods (require admin_token):

1. controlUpsertTenant, controlListTenants, controlUpsertProject
2. controlCreateApiKey, controlListApiKeys, controlListStaleApiKeys, controlRevokeApiKey, controlRotateApiKey
3. controlCreateAlertRoute, controlListAlertRoutes, controlUpdateAlertRouteStatus, controlListAlertDeliveries
4. controlEnqueueIncidentPublishJob, controlListIncidentPublishJobs, controlReplayIncidentPublishJobs
5. controlUpsertTenantQuota, controlGetTenantQuota, controlDeleteTenantQuota
6. controlUpsertSandboxBudget, controlGetSandboxBudget, controlDeleteSandboxBudget, controlListSandboxBudgets
7. controlListAuditEvents, controlGetTenantDashboard, controlGetTenantDiagnostics
8. controlGetTenantIncidentPublishRollup, controlGetTenantIncidentPublishSlo, controlGetTenantTimeseries, controlGetTenantKeyUsage

Error model

1. AionisApiError: API returned non-2xx response.
2. AionisNetworkError: request timeout/network failure.

Capability-aware helpers:

1. isBackendCapabilityUnsupportedError(err)
2. parseBackendCapabilityErrorDetails(err.details)
3. isShadowDualWriteStrictFailureError(err)
4. parseShadowDualWriteStrictFailureDetails(err.details)

Example:

import { AionisApiError, isBackendCapabilityUnsupportedError } from "@aionis/sdk";

try {
  await client.packExport({ scope: "default" });
} catch (err) {
  if (isBackendCapabilityUnsupportedError(err)) {
    // err.details now carries capability contract fields
    console.log(err.details.capability, err.details.failure_mode, err.details.degraded_mode);
  } else if (err instanceof AionisApiError) {
    console.error(err.code, err.message);
  }
}

Smoke

set -a; source .env; set +a
npm run sdk:smoke

Build (repo local)

npm run sdk:build
npm run sdk:pack-dry-run
npm run sdk:release-check