@alvera-ai/platform-sdk 0.10.0-rc.2 → 0.10.0-rc.21

package/.agent/tools.md

@@ -0,0 +1,546 @@
+# `tools` — block authoring reference
+
+Family: **INFRA** (anchor for `intent = data_exchange`) +
+**WORKFLOWS** (tagged for `intent ∈ {sms, email, voice, export}`).
+
+A tool is an authenticated connection to an external system that
+the platform invokes to **execute actions**. Two orthogonal
+dimensions:
+
+- **intent** classifies what the tool DOES (move data, send a
+  message, render a report)
+- **body type** declares HOW the tool connects (S3, SFTP, SQL,
+  REST, AWS Lambda, …) via a polymorphic discriminator
+
+A datalake can own many tools. Some tools nest under a data source
+(`data_source_id` populated — typical for ingestion-receiving
+tools like `manual_upload`); others are standalone and reachable
+to any workflow on the datalake.
+
+## 1. Wire shape
+
+SDK TypeScript type (request shape; server-derived fields excluded):
+
+```
+   import type { ToolRequestWritable }
+     from '@alvera-ai/platform-sdk'
+```
+
+No runtime validator is exported — validation is server-authoritative
+(a bad body returns a 422 `AlveraApiError`; see `errors.md`).
+
+Intent enum (typed):
+
+```
+   import { ToolIntent } from '@alvera-ai/platform-sdk'
+
+   ToolIntent.DATA_EXCHANGE   // fetch / push payloads
+   ToolIntent.SMS             // outbound text messages
+   ToolIntent.EMAIL           // outbound email
+   ToolIntent.VOICE           // outbound voice / voicemail
+   ToolIntent.EXPORT          // report / extract generation
+   ToolIntent.STATUS_POLLER   // polls external systems for
+                              //  delivery/action status; paired
+                              //  with action status updaters
+                              //  (see action_status_updaters.md)
+   ToolIntent.CHAT_COMPLETION // OpenAI-compatible chat-completion
+                              //  endpoint; paired with AI agents
+                              //  (see ai_agents.md)
+   ToolIntent.CONTEXT_EXTRACTION
+                              // LLM-backed enrichment that extracts
+                              //  structured context from raw rows;
+                              //  paired with AI agents (see
+                              //  ai_agents.md). Like CHAT_COMPLETION,
+                              //  pairs with rest_api body against an
+                              //  OpenAI-compatible endpoint.
+```
+
+Polymorphic body dispatch — the `body.tool_body_type` field is
+the discriminator. Each branch is its own TypeScript type:
+
+```
+   tool_body_type = 'manual_upload'  →  manual-upload receiver
+                                        (presigned-URL upload path)
+   tool_body_type = 's3'             →  AWS S3 / R2 / custom-endpoint
+                                        object storage
+   tool_body_type = 'sftp'           →  SFTP file transfer
+   tool_body_type = 'sql_database'   →  SQL (Postgres, MySQL, …)
+   tool_body_type = 'rest_api'       →  generic REST endpoint
+   tool_body_type = 'sns'            →  AWS SNS topic (used for
+                                        SMS / push notifications)
+   tool_body_type = 'sharepoint'     →  Microsoft Graph SharePoint
+   tool_body_type = 'aws_lambda'     →  invoke a Lambda function
+   tool_body_type = 'sqs'            →  AWS SQS queue
+   tool_body_type = 'cloud_watch_log_group'
+                                     →  AWS CloudWatch Logs poller
+                                        (paired with
+                                         ToolIntent.STATUS_POLLER)
+   tool_body_type = 'email'          →  dedicated email-provider body
+                                        (SendGrid, SES, SMTP-bridge)
+                                        — alternative to using
+                                        rest_api for email intents
+```
+
+The authoritative enum lives in the generated `ToolBodyTypeEnum`
+export from `@alvera-ai/platform-sdk` — consult the type for the
+complete set, since new body types land independently of doc
+revisions.
+
+## 2. Rules the type cannot encode
+
+### `intent` and `tool_body_type` are loosely coupled
+
+The TypeScript type lets you combine any intent with any body
+type, but the platform validates the pairing semantically at
+create time:
+
+```
+   data_exchange  →  s3, sftp, sql_database, rest_api,
+                     manual_upload, aws_lambda, sharepoint, sqs
+   sms            →  sns, rest_api (provider-specific)
+   email          →  email (dedicated body), rest_api,
+                     aws_lambda (custom dispatchers)
+   voice          →  rest_api (Twilio Voice, etc.)
+   export         →  s3, aws_lambda
+   status_poller  →  cloud_watch_log_group, rest_api
+   llm_enrichment → rest_api (against an OpenAI-compatible LLM
+                              endpoint; the platform appends
+                              /chat/completions to base_url; the
+                              tool is the complete LLM provider
+                              adapter and AI agents bind it for
+                              structured row enrichment)
+```
+
+A misaligned pair (e.g. `intent: sms` + `tool_body_type: sftp`)
+returns a `422` with `body.tool_body_type` in `errors`.
+
+### `data_source_id` is optional but discriminator-aware
+
+When set, the tool is **embedded under a data source** — its
+lifecycle is tied to the parent data source, and ingestion paths
+expect it at that scope. When omitted, the tool is **standalone**
+on the datalake — available to any workflow that names it.
+
+The body type itself signals the typical pattern: `manual_upload`
+is almost always embedded (the data source IS the upload sink);
+`sns`, `rest_api`, `sql_database` are typically standalone.
+
+### Body-type sub-fields are validated against the matching discriminator branch (server-side)
+
+Each branch has its own required-list. Common patterns:
+
+```
+   sns body                 region, auth_method, plus EITHER
+                              (access_key_id + secret_access_key
+                                + optional endpoint_url)
+                            OR (iam_role)
+
+   sql_database body        db_type, db_host, db_port, db_name,
+                              auth_method, db_username,
+                              db_password (or iam_role)
+
+   s3 body                  region, bucket, auth_method,
+                              access_key_id, secret_access_key
+                              (or iam_role), optional base_path
+
+   sftp body                hostname, port, username, auth_method,
+                              password (or private_key)
+
+   rest_api body            base_url, auth_method (oauth2 /
+                              oidc / api_key / basic), plus the
+                              corresponding credential block
+```
+
+The full per-branch shape lives in
+`packages/sdk/src/generated/types.gen.ts` under the matching
+`Tool<Type>BodyWritable` types.
+
+### `status` field gates whether the tool can be invoked
+
+```
+   active     tool is invocable; test-invocation + workflow steps work
+   inactive   tool exists but invocations short-circuit with
+                an explanatory error envelope
+```
+
+Most callers set `status: 'active'` on create; flipping to
+`inactive` is the soft-delete / pause pattern.
+
+### `aws_lambda` body has a second discriminator: `type`
+
+Inside the `aws_lambda` body (selected by the outer
+`tool_body_type: "aws_lambda"`), the wire carries a second
+discriminator field literally named `type`:
+
+```
+   body.type = "managed"   →  the platform owns the function;
+                              create + deploy + delete go through
+                              the platform's CloudFormation stack
+   body.type = "external"  →  the function is operator-managed in
+                              an AWS account; the platform only
+                              invokes it
+```
+
+The two paths require disjoint field sets:
+
+```
+   type: "managed"
+     required:   ssm_config_key (string — names the config
+                                 partition in SSM Parameter Store
+                                 the function reads at runtime)
+     accepted:   secrets[]      (array of { key, value } — material
+                                 the function reads as runtime
+                                 secrets; values are sensitive,
+                                 treat as write-only on the manifest
+                                 side via `<%= name %>` per §6 gotcha 10)
+                 env_vars[]     (array of { key, value } — passed
+                                 to the function as plain environment
+                                 variables; non-sensitive)
+     server-set: function_arn   (populated after deploy succeeds)
+                 stack_id, stack_name, stack_status
+                                (CloudFormation tracking; see
+                                 §2 "aws_lambda tools have an
+                                 async deployment lifecycle")
+
+   type: "external"
+     required:   function_arn   (the existing AWS function to invoke)
+                 auth_method    ("access_key" or "iam_role")
+     access_key:  access_key_id required;
+                  secret_access_key write-only at create
+     iam_role:    no AWS credentials required; the platform
+                  assumes the role at invocation time
+```
+
+### `aws_lambda` tools have an async deployment lifecycle
+
+For `type: "managed"`, creating the tool registers the row but
+DOES NOT deploy. An out-of-band deployment step packages and
+uploads the function; poll the tool's `deployment_status` field:
+
+```
+   pending     POST returned; deployment job enqueued
+   deploying   code being uploaded to AWS
+   deployed    function is invocable; testInvocation will route to it
+   failed      deployment error; check `deployment_error` field
+```
+
+Two consumer-relevant consequences:
+
+- **Managed tools cannot be created with `status: "active"`.**
+  The platform rejects with `/status: "cannot be set to active
+  until Lambda deployment is complete"`. Create with
+  `status: "draft"` (the typical pattern for managed lambdas),
+  trigger deployment, poll until `deployment_status: "deployed"`,
+  then PUT to flip `status` to `"active"`.
+- **`function_arn` is server-populated for managed tools.** Do
+  not supply it on POST/PUT for `type: "managed"` — the platform
+  writes it after the CloudFormation stack reaches a
+  create-complete state.
+
+For `type: "external"`, there is no deployment phase — the row
+is invocable as soon as the create returns, and `function_arn`
+is caller-supplied. Other body types (`s3`, `sns`, `rest_api`,
+…) likewise have no deployment phase.
+
+### `rest_api` body with `auth_method: "oidc"` probes the token endpoint at create
+
+For `auth_method: "oidc"`, the platform fetches an access token
+from the configured `oidc_issuer_url` using
+`oidc_client_id` + `oidc_client_secret` **before** the row is
+written. The probe surfaces in field-level rejections:
+
+```
+   401 from token endpoint     →  /oidc_client_id:
+                                   "invalid credentials — token
+                                    endpoint returned 401"
+   other non-200               →  /oidc_issuer_url:
+                                   "token endpoint returned HTTP {status}"
+   network unreachable         →  /oidc_issuer_url:
+                                   "cannot reach token endpoint: {reason}"
+```
+
+The probe is skipped when any of the required OIDC fields
+(`oidc_issuer_url`, `oidc_client_id`, `oidc_client_secret`) are
+missing — in that case the request fails on the missing-field
+check before any HTTP call. Other `auth_method` values
+(`oauth2`, `api_key`, `basic`, `none`) do not probe — only the
+OIDC path runs the token-endpoint reachability check.
+
+The probe runs on PUT too; an update that re-supplies any of
+the three OIDC fields re-validates the token endpoint, so a
+silent OIDC-provider outage can fail an otherwise-cosmetic
+PUT.
+
+## 3. Field ownership conventions
+
+### Caller-supplied
+
+```
+   identification + metadata
+     name                 human-readable label (unique per datalake)
+     description          (nullable) free text
+     intent               ToolIntent enum value
+     status               "draft" | "active" | "inactive" | "error" | "marked_for_deletion"
+                            'draft'               — created but unconfigured (typical for
+                                                    lambda tools awaiting deployment)
+                            'active'              — invocable; the steady state
+                            'inactive'            — paused / soft-deleted; invocations
+                                                    short-circuit (see §2)
+                            'error'               — failure state; surfaces via UI banners
+                                                    and gates re-invocation until resolved
+                            'marked_for_deletion' — cleanup in flight (lambda undeploy etc.);
+                                                    transient before DB row removal
+
+   scoping
+     datalake_id          parent datalake (UUID)
+     data_source_id       (optional) parent data source for embedded
+                          tools; omit for standalone
+
+   body (polymorphic — required keys depend on tool_body_type)
+     tool_body_type       discriminator — names which branch shape
+                          the rest of `body` must satisfy
+     <branch-specific>    auth + endpoint + credential fields
+                          (use `<%= name %>` Eta refs for credentials;
+                          never literal values)
+```
+
+### Server-derived
+
+```
+   id                     UUID
+   slug                   derived from name (lowercase + hyphen)
+   created_at             ISO timestamp
+   updated_at             ISO timestamp
+   deployment_status      lambda tools only
+   deployment_error       lambda tools only, when status="failed"
+```
+
+The slug, like every other resource, is the canonical handle for
+downstream references after create — never pre-compute it
+client-side.
+
+## 4. Error envelopes
+
+A `422` from `POST` / `PUT` returns:
+
+```
+   {
+     "errors": {
+       "field.path": ["check message", …],
+       "body.tool_body_type": ["is invalid"],
+       …
+     }
+   }
+```
+
+Walking each entry:
+
+1. Look up the field on `ToolRequestWritable` (or the relevant
+   `Tool<Type>BodyWritable` branch when the path starts with
+   `body.`). The TS type's JSDoc names the semantic role.
+2. Read the 422 `detail` for the precise constraint that fired
+   (the field tables in this MD list each branch's required-list).
+3. For `body.<...>` failures, the FIRST diagnostic is usually
+   `tool_body_type` — fix the discriminator before chasing other
+   fields, because the wrong branch's required-list will fire
+   spuriously when the discriminator is wrong.
+
+Common rejections:
+
+```
+   field check                                    cause
+   ─────────────────────────────                 ─────────────────────────────
+   "is invalid" on intent                         value not in ToolIntent enum
+   "is invalid" on tool_body_type                 value not in
+                                                    ToolBodyTypeEnum
+   "is invalid" on body                           intent ↔ body_type pairing
+                                                    rejected at platform level
+   "can't be blank" on a body sub-field           branch-specific required
+                                                    field omitted
+   "must match auth_method" on credentials        e.g. `iam_role` set but
+                                                    `access_key_id` also supplied
+```
+
+## 5. Lifecycle
+
+### Create
+
+`POST /tenants/:tenant_slug/datalakes/:datalake_slug/tools`
+returns `201` with the full tool shape including server-derived
+fields. For non-lambda body types the tool is invocable
+immediately; for `aws_lambda` the deployment is async (see §2).
+
+### Test invocation
+
+`POST /tenants/:tenant/datalakes/:datalake/tools/:id/test-
+invocation` exercises the tool end-to-end against the live
+external system.
+
+The request body wraps the call payload under `tool_call`, whose
+own polymorphic `tool_call_type` discriminator selects the call
+shape:
+
+```typescript
+await api.tools.testInvocation(
+  tenantSlug, datalakeSlug, toolId,
+  {
+    tool_call: {
+      tool_call_type: 'sms_request',   // 'email_request' | ...
+      to:   { type: 'custom', body: '+15551234567' },
+      body: { type: 'custom', body: 'Hello' },
+      sms_type: 'transactional',       // sms_request-specific
+    },
+  },
+)
+```
+
+`to` and `body` are each `{ type, body }` embeds — `type: 'custom'`
+inlines the value verbatim; `type: 'system'` references a
+platform-shipped template (see `templates.md`). Variant-specific
+fields carry their own enums and constraints; the per-branch
+required-list:
+
+```
+   tool_call_type: 'sms_request'
+     required:   to, body, sms_type
+     enums:      sms_type ∈ { 'transactional' (default), 'promotional' }
+
+   tool_call_type: 'email_request'
+     required:   to, subject, body
+     embeds:     TemplateConfig variants accepted on each ({ type:
+                 'custom', body } or { type: 'identity' } or
+                 { type: 'system', path }); 'null' is not valid here
+
+   tool_call_type: 'rest_api_request'
+     required:   path, method, pagination_context_template
+     enums:      method ∈ HTTP methods (GET, POST, PUT, PATCH, DELETE,
+                 HEAD, OPTIONS)
+     optional:   body, params (each TemplateConfig — 'identity' or
+                 'custom' both accepted)
+
+   tool_call_type: 'sql_query'
+     required:   query (TemplateConfig — Liquid template producing
+                        the SQL string)
+
+   tool_call_type: 'aws_lambda_request'
+     required:   payload (TemplateConfig — 'identity' acceptable)
+     constraints: timeout_ms in inclusive range [1000, 900_000]
+                  (defaults to 30_000 ms when omitted)
+
+   tool_call_type: 'sftp_request'
+     required:   path, content_type
+     enums:      content_type ∈ closed set (json, ndjson, csv, ...);
+                 the SDK type names the live set per branch
+     format:     path validated against an absolute-path pattern
+                 and a maximum length
+
+   tool_call_type: 'microsoft_share_point_excel_request'
+     required:   every field of the branch
+     constraints: sheet_number >= 0 (0-indexed; negative values are
+                  rejected with a "greater than -1" message)
+```
+
+Liquid template bodies (`query`, `payload`, body/params on
+`rest_api_request`, `sms_request` body, `email_request` body) are
+parsed at create time — invalid Liquid syntax surfaces as a field
+rejection on the corresponding TemplateConfig path, not on the
+outer request.
+
+The response shape:
+
+```
+   {
+     id:           UUID of the recorded invocation
+     status:       "success" | "error"
+     error_message: string | null
+     tool_call:    the input echoed back, with provider metadata
+   }
+```
+
+This endpoint **never returns a 5xx for tool-side failures** —
+provider errors (bad credentials, network refused, misconfigured
+auth) surface as `status: "error"` with `error_message` populated.
+Only platform-internal failures (DB unreachable, etc.) produce
+5xx. Treat 5xx as infra noise; treat `200 + status:"error"` as a
+real (and handleable) configuration problem.
+
+### Update
+
+`PUT /tenants/:tenant/datalakes/:datalake/tools/:id` replays the
+full body — no PATCH. The polymorphic discriminator MUST match
+the existing row's `tool_body_type`; changing body type requires
+delete + recreate.
+
+### Delete
+
+`DELETE /tenants/:tenant/datalakes/:datalake/tools/:id` removes
+the row. For `aws_lambda` tools, this also enqueues a
+`trigger_lambda_deletion` job — poll until the AWS function is
+gone. Other body types delete synchronously.
+
+### Ordering
+
+A tool MUST be created AFTER its parent datalake reaches
+`status: "ready"`, and (if embedded) AFTER its parent data source
+exists. Workflows and data activation clients reference tools by id, so any
+downstream resource that names a tool must apply AFTER it.
+
+## 6. Gotchas
+
+1. **Discriminator wire name is `tool_body_type`** — not `type`,
+   not `kind`, not `__type__`. Always use the wire name on the
+   request body.
+
+2. **`manual_upload` body is the only branch with no auth /
+   endpoint fields** — its presigned URLs are issued by the
+   platform per-upload. `body: { tool_body_type: 'manual_upload' }`
+   with no other body fields is the full create body.
+
+3. **`sns` tools with `iam_role` auth + no `endpoint_url` MUST be
+   tested against real AWS** — `ExAws.Config.AuthCache` refreshes
+   SSO credentials at invocation time. In dev / E2E, use
+   `auth_method: 'access_key'` + `endpoint_url:
+   'http://localhost:4566'` for LocalStack routing.
+
+4. **Test-invocation graceful-error contract is load-bearing** —
+   any code path that crashes the test-invocation route into a 500
+   is a regression. Misconfigured tools must surface
+   `status: "error"` + non-empty `error_message`. If you see a
+   5xx, file a platform bug, do not retry.
+
+5. **Standalone vs embedded tool routing differs at list time**
+   — `tools.list(tenant, datalake)` returns ALL tools on the
+   datalake (standalone + embedded). To find tools owned by a
+   specific data source, filter the list client-side on
+   `data_source_id`.
+
+6. **Tool slug uniqueness is per-datalake, not per-tenant** —
+   two datalakes on the same tenant can have tools with the same
+   slug. Always scope tool references via the datalake slug,
+   never just the tool slug.
+
+7. **`tools.metadata(tenant, datalake)` returns a Markdown
+   catalog** — useful as a discovery surface for downstream
+   tooling. `tools.metadataDetails(tenant, datalake, toolId)`
+   returns Markdown for a single tool including the body
+   discriminator + per-branch fields.
+
+8. **`PUT` replays the full body** — to flip `status` from
+   `active` to `inactive`, resubmit the entire body including all
+   credential / endpoint fields. Forgetting the body branch
+   discriminator on PUT triggers the "tool_body_type required"
+   rejection.
+
+9. **Lambda deployment_status is the readiness signal, not
+   `status`** — for `aws_lambda` tools, `status: "active"` only
+   means "row exists and is invocation-eligible if deployed".
+   The actual readiness is `deployment_status: "deployed"`.
+
+10. **Credentials in the body MUST go through `<%= name %>`
+    Eta references** when the tool is authored via a manifest — never
+    literal strings on disk. The flat top-level identifier form is the
+    safe shape (`<%= secrets.name %>` nested under a `secrets` object
+    silently renders the string `"undefined"` if the key is missing).
+    The SDK does not enforce this (it accepts literals), but secret
+    references are the required operating mode for any non-test
+    environment.

package/.agent/type_naming.md

@@ -0,0 +1,131 @@
+# Type naming
+
+The SDK's TypeScript codegen emits two type variants per
+resource — a request shape (for POST/PUT bodies) and a response
+shape (for GET output). They differ in which fields they
+include.
+
+## Writable suffix for request shapes
+
+Request types carry a `Writable` suffix. The codegen
+auto-excludes any field marked `readOnly` in the OpenAPI spec —
+these are the server-derived fields (`id`, `slug`, `created_at`,
+`updated_at`, `status`, etc. — enumerated in the next section).
+
+```typescript
+import type {
+  DatalakeRequestWritable,    // POST/PUT body
+  DatalakeResponse,           // GET output
+} from '@alvera-ai/platform-sdk'
+```
+
+Same convention for every resource:
+
+```
+   <Resource>RequestWritable        POST/PUT body (request shape)
+   <Resource>Response               GET output (response shape with
+                                      server-derived fields included)
+```
+
+## Server-derived fields auto-excluded from Writable
+
+Every resource carries a consistent set of fields the platform
+server derives on create. These appear in `<Resource>Response`
+types but are NEVER part of `<Resource>RequestWritable` types —
+the codegen auto-excludes them based on `readOnly` markers in
+the OpenAPI spec:
+
+```
+   id              UUID, allocated on create
+   slug            derived from `name` via the platform's
+                     slug-generation (lowercase + hyphenate +
+                     de-duplicate within scope)
+   created_at      ISO 8601 timestamp
+   updated_at      ISO 8601 timestamp
+   status          resource-specific lifecycle enum
+                     (e.g. "new" → "ready" → ... per the
+                     resource's MD §5)
+   status_reason   nullable; populated when status enters a
+                     terminal-failure state
+```
+
+Including any of these in a POST/PUT body triggers a layer-1
+422 with an "unknown key" detail. The typed `*RequestWritable`
+doesn't expose these fields, so TypeScript prevents it at
+compile time when consumers use the typed methods.
+
+### Never pre-compute the slug client-side
+
+Slugs are derived from `name` server-side and de-duplicated
+within scope (per-resource — usually datalake-scoped for
+datalake-owned resources, tenant-scoped for tenant-level
+resources). A client-computed slug that conflicts with an
+existing row gets a different suffix server-side, leaving the
+client's local state out of sync.
+
+The canonical pattern:
+
+```typescript
+// 1. create — slug returned in the response
+const { data: created } = await api.tools.create(
+  tenantSlug, datalakeSlug, body,
+)
+const toolSlug = created.slug   // <-- canonical
+
+// 2. downstream references use the returned slug
+await api.tools.get(tenantSlug, datalakeSlug, toolSlug)
+```
+
+Never:
+
+```typescript
+// ❌ wrong — client-computed slug can drift from server-side
+const toolSlug = body.name.toLowerCase().replace(/\s+/g, '-')
+```
+
+### Per-resource extras
+
+Some resources have additional server-derived fields beyond
+the universal set (e.g. AWS Lambda tools' `deployment_status`
++ `deployment_error`; data-activation-client `last_run_at`).
+Each resource's MD §3 (Field ownership) lists its full
+server-derived set.
+
+## No client-side validators
+
+The SDK ships **types only** — there is no paired runtime validator to
+import (`v<Resource>RequestWritable` no longer exists). Validation is
+server-authoritative: submit the body and handle the server's 422
+`AlveraApiError` if it's malformed (see `errors.md`). If you author config
+through the `alvera` CLI, `alvera plan` validates locally against the spec
+before any HTTP call.
+
+## Enum types
+
+Enums are exported as TypeScript const-style values (per the
+SDK's strict-TS conventions — no TypeScript-native `enum`
+keyword):
+
+```typescript
+import { ToolIntent } from '@alvera-ai/platform-sdk'
+
+ToolIntent.DATA_EXCHANGE   // wire value: "data_exchange"
+ToolIntent.SMS             // wire value: "sms"
+```
+
+The wire value is always snake_case; the TS-side identifier is
+UPPER_SNAKE for readability. Each resource's MD names its
+relevant enum types.
+
+## List response types
+
+List endpoints return a typed envelope: `<Resource>List-
+Response` with `data: <Resource>Response[]` and `meta:
+PaginationMeta`:
+
+```typescript
+import type { ToolListResponse } from '@alvera-ai/platform-sdk'
+
+const { data } = await api.tools.list(tenantSlug, datalakeSlug)
+// data is ToolListResponse: { data: ToolResponse[], meta: PaginationMeta }
+```