@alvera-ai/platform-sdk 0.1.0 → 0.2.1

package/README.md

@@ -16,20 +16,26 @@ pnpm add @alvera-ai/platform-sdk
 ## Quick start
 
 ```ts
-import { createPlatformApi } from '@alvera-ai/platform-sdk';
+import { createPlatformApi, createSession } from '@alvera-ai/platform-sdk';
 
-const api = createPlatformApi({
-  baseUrl: 'https://admin.alvera.ai',
-  apiKey: process.env.ALVERA_API_KEY!,
+const baseUrl = 'https://admin.alvera.ai';
+
+// 1. Exchange credentials for a session token
+const session = await createSession({
+  baseUrl,
+  email: process.env.ALVERA_EMAIL!,
+  password: process.env.ALVERA_PASSWORD!,
+  tenantSlug: 'acme',
 });
 
-// Health check
+// 2. Build the API client with that token
+const api = createPlatformApi({ baseUrl, sessionToken: session.sessionToken });
+
+// 3. Use it
 await api.ping();
 
-// List datalakes for a tenant
 const { data: datalakes } = await api.datalakes.list('acme');
 
-// Create a data source
 const { data: ds } = await api.dataSources.create('acme', 'acme-health', {
   name: 'Acme EMR',
   uri: 'our-emr:acme',
@@ -38,7 +44,6 @@ const { data: ds } = await api.dataSources.create('acme', 'acme-health', {
   is_default: true,
 });
 
-// Attach a tool to the data source
 const { data: tool } = await api.tools.create('acme', {
   name: 'Acme Manual Upload',
   intent: 'data_exchange',
@@ -51,20 +56,46 @@ const { data: tool } = await api.tools.create('acme', {
 
 ## Authentication
 
-The SDK authenticates with an `X-API-Key` header. Obtain an API key for your
-tenant from your Alvera admin.
+The SDK uses **session-based** auth.
+
+1. Call `createSession({ baseUrl, email, password, tenantSlug })` with your
+   Alvera login credentials and the tenant you want to operate on.
+2. The returned `sessionToken` is a Bearer token, valid for 24 hours by
+   default (override with `expiresIn`, max 30 days).
+3. Pass the token into `createPlatformApi({ baseUrl, sessionToken })`.
+4. When done, optionally call `revokeSession()` to invalidate the token.
+
+```ts
+import { createSession, createPlatformApi, revokeSession } from '@alvera-ai/platform-sdk';
+
+const session = await createSession({
+  baseUrl, email, password, tenantSlug: 'acme', expiresIn: 3600,
+});
+const api = createPlatformApi({ baseUrl, sessionToken: session.sessionToken });
+// ... use api ...
+await revokeSession();
+```
+
+`session.expiresAt` is an ISO-8601 timestamp — check it before long-running
+work and re-authenticate if needed.
 
 ## Resources
 
 | Resource                | Operations                                  |
 |-------------------------|---------------------------------------------|
-| `ping`                  | health check                                |
-| `datalakes`             | `list`, `get`                               |
-| `dataSources`           | `list`, `create`, `update`                  |
-| `tools`                 | `list`, `get`, `create`, `update`, `delete` |
-| `genericTables`         | `list`, `create`                            |
-| `actionStatusUpdaters`  | `list`, `create`, `update`                  |
-| `aiAgents`              | `list`, `get`, `create`, `update`, `delete` |
+| `ping`                   | health check                                                                 |
+| `sessions`               | `verify`                                                                     |
+| `datasets`               | `search`                                                                     |
+| `datalakes`              | `list`, `get`, `create`                                                      |
+| `dataSources`            | `list`, `create`, `update`                                                   |
+| `tools`                  | `list`, `get`, `create`, `update`, `delete`                                  |
+| `genericTables`          | `list`, `create`                                                             |
+| `actionStatusUpdaters`   | `list`, `create`, `update`                                                   |
+| `aiAgents`               | `list`, `get`, `create`, `update`, `delete`                                  |
+| `connectedApps`          | `list`, `get`, `create`, `update`, `syncRoutes`, `resolvePage`, `updateMessageTracking` |
+| `dataActivationClients`  | `ingest`, `ingestFile`, `createUploadLink`                                   |
+| `mdm`                    | `verify`                                                                     |
+| `workflows`              | `execute`                                                                    |
 
 Tenant and datalake provisioning are performed by Alvera admins — contact your
 representative to onboard a new tenant.
@@ -82,6 +113,87 @@ try {
 }
 ```
 
+## CLI
+
+The package ships a companion CLI (`alvera`) for ad-hoc calls against the
+platform API. Install the package (globally, or via `npx`) and authenticate
+once — subsequent commands reuse the stored session.
+
+```bash
+# Run without installing
+npx @alvera-ai/platform-sdk --help
+
+# Or install globally
+npm install -g @alvera-ai/platform-sdk
+alvera --help
+```
+
+### Configuration
+
+`alvera` stores state under `~/.alvera-ai/`, AWS CLI–style:
+
+| File                        | Purpose                                           |
+|-----------------------------|---------------------------------------------------|
+| `~/.alvera-ai/config`       | Per-profile defaults (base URL, tenant, email)    |
+| `~/.alvera-ai/credentials`  | Per-profile session token and expiration (0600)   |
+
+Both files are INI. The default profile is `[default]`; additional profiles
+live under `[profile <name>]` in `config` and `[<name>]` in `credentials`.
+
+Every command accepts `--profile <name>`. Environment variables
+(`ALVERA_PROFILE`, `ALVERA_BASE_URL`, `ALVERA_TENANT`, `ALVERA_EMAIL`,
+`ALVERA_PASSWORD`, `ALVERA_SESSION_TOKEN`) take precedence over file values.
+
+### Getting started
+
+```bash
+alvera configure                          # set base URL + default tenant
+alvera login --email me@acme.com --tenant acme
+alvera ping
+alvera datalakes list
+alvera tools create --body-file tool.json
+alvera logout
+```
+
+Multiple environments via profiles:
+
+```bash
+alvera --profile staging login --base-url https://admin.staging.alvera.ai --tenant acme
+alvera --profile staging datalakes list
+```
+
+### Command surface
+
+```
+alvera configure
+alvera login   [--email] [--password] [--tenant] [--base-url] [--expires-in]
+alvera logout
+alvera whoami
+alvera ping
+
+alvera datalakes              list | get <id> | create
+alvera data-sources           list <datalake> | create <datalake> | update <datalake> <id>
+alvera tools                  list | get <id> | create | update <id> | delete <id>
+alvera generic-tables         list <datalake> | create <datalake>
+alvera action-status-updaters list | create | update <id>
+alvera ai-agents              list <datalake> | get <datalake> <id> | create <datalake>
+                              | update <datalake> <id> | delete <datalake> <id>
+alvera sessions-verify
+alvera datasets               search <dataset> [--datalake-id] [--page] [--page-size]
+alvera connected-apps         list <datalake> | get <datalake> <id> | create <datalake>
+                              | update <datalake> <id> | sync-routes <datalake> <id>
+                              | resolve-page <slug> | update-message-tracking <slug>
+alvera data-activation-clients  ingest <slug> | ingest-file <slug> <key>
+                                | upload-link <slug> <filename> [--content-type]
+alvera mdm                    verify <datalake>
+alvera workflows              execute <workflow-slug>
+```
+
+All `create` / `update` commands require `--body '<json>'` or `--body-file <path>`
+(use `-` for stdin). A tenant positional argument is optional when the profile
+has a default tenant configured. Output is pretty-printed JSON on stdout;
+status messages and prompts go to stderr so responses stay pipeable.
+
 ## Regenerating the typed client
 
 The typed client is generated from the live OpenAPI spec at

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}