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

package/.agent/mutations.md

@@ -0,0 +1,152 @@
+# Mutations
+
+The platform's CRUD verbs follow three uniform rules: POST
+creates, PUT replays the full body on update, DELETE removes.
+PATCH is reserved for limited surgical exceptions explicitly
+called out below.
+
+Non-CRUD methods on the SDK are out of scope for this page —
+surgical RESTful sub-actions (`.syncRoutes`, `.resolvePage`,
+`.testInvocation`), artifact issuers (`.createUploadLink`,
+`.createDownloadLink`), and async action triggers (`.run`,
+`.execute`) each have their own per-method semantics
+documented in their resource's MD.
+
+## POST — create
+
+`POST /<resource>` returns `201 Created` with the full
+`<Resource>Response` body, including all server-derived
+fields (`id`, `slug`, `status`, timestamps — see
+`type_naming.md` "Server-derived fields"). Use this returned
+body for any downstream references — never pre-compute
+server-derived fields client-side.
+
+## PUT — full-body update
+
+`PUT /<resource>/:slug` is a full-body replay, not a partial
+update. To change a single field, submit the ENTIRE current
+body with the changed field substituted in:
+
+```typescript
+// 1. fetch current
+const { data: current } = await api.tools.get(
+  tenantSlug, datalakeSlug, toolId,
+)
+
+// 2. mutate in memory
+const next = { ...current, status: 'inactive' }
+
+// 3. PUT the full mutated body
+const { data: updated } = await api.tools.update(
+  tenantSlug, datalakeSlug, toolId, next,
+)
+```
+
+Omitting required fields on `PUT` triggers a 422 on those
+fields, even when they're unchanged from the stored row — `PUT`
+replaces the whole resource. The server returns the failure as a
+422 `AlveraApiError` (see `errors.md`).
+
+## PATCH exceptions (surgical partial-body updates)
+
+A small set of update methods take a narrow partial body via
+PATCH instead of the full-body PUT replay. Each is named here,
+documents its partial-body contract in the TypeScript
+wrapper's JSDoc, and is flagged in its per-resource MD §5
+(Lifecycle):
+
+| SDK method                                  | Resource MD          |
+|---------------------------------------------|----------------------|
+| `api.connectedApps.updateMessageTracking`   | `connected_apps.md`  |
+
+For every other update method, the default rule applies:
+PUT replays the full body.
+
+> This is the canonical index of PATCH exceptions. If a
+> future method joins, it lands here. If you encounter a
+> method whose JSDoc claims partial-body behavior but it
+> isn't listed here, this index is wrong and needs a
+> refresh.
+
+## Discriminator on PUT must match
+
+For polymorphic resources (tools, datalakes' cloud storage,
+etc.), the body's discriminator value MUST match the
+existing row's discriminator on update. The platform rejects
+discriminator changes mid-life with a 422 on the
+discriminator field's pointer.
+
+Changing body type requires DELETE + recreate, not PUT.
+
+## Polymorphic discriminator naming
+
+Resources with polymorphic body shapes use an explicit
+discriminator field at the wire level. The discriminator's
+**wire name** is what the SDK type expects; the
+platform-internal struct name on the server side may differ.
+
+Use the wire name everywhere:
+
+| Resource                       | Discriminator (wire)     |
+|--------------------------------|--------------------------|
+| Tool body                      | `tool_body_type`         |
+| Datalake cloud-storage embed   | `cloud_storage_type`     |
+
+The wire name is what appears in your request body's JSON
+and in `<Resource>RequestWritable` TypeScript types. Never
+use the server-internal struct name (e.g. `__type__`) —
+that's an implementation detail not surfaced to consumers.
+
+Each resource's MD §1 (Wire shape) names its discriminator
+and lists every branch's TypeScript type.
+
+## DELETE — usually synchronous
+
+`DELETE /<resource>/:slug` removes the row. A few resources
+have semantic guards (e.g. cannot delete a default-flagged
+data activation client; cannot delete a datalake with
+dependents) that surface as 422s with `source.pointer`
+naming the field that's blocking the delete.
+
+For asynchronous deletes (e.g. AWS Lambda tools' out-of-band
+cleanup), poll the resource's status until it's gone — see
+`async.md`.
+
+## URL path is authoritative over body for parent scopes
+
+Every nested resource lives under a URL of the form:
+
+```
+/api/v1/tenants/{tenant_slug}/datalakes/{datalake_slug}/<resource>[/{id}]
+```
+
+The body usually carries a `datalake_id` (and sometimes
+`tenant_id`) field naming the same parent. The platform
+treats the **URL path as authoritative**: if the body
+references a different parent than the URL names, the URL
+wins and the body field is silently ignored. The row is
+created under the URL's parent regardless of the body.
+
+This holds for both POST and PUT, and across every nested
+resource confirmed in tests so far (data sources, tools,
+action status updaters, data activation clients, …). The
+practical consequence:
+
+- **Never use body fields to "redirect" a write to a
+  different datalake.** If you need to target a different
+  parent, change the URL.
+- **Reusing a body across datalakes is safe.** A stored
+  `datalake_id` snapshot from a previous call can be sent
+  on a write under any URL — the URL governs where it lands.
+- **422s on `/datalake_id` mismatch don't happen.** The
+  platform doesn't reject a body whose `datalake_id` differs
+  from the URL — it just ignores the body value.
+
+## No bulk mutations on standard CRUD
+
+Each standard mutation request mutates ONE resource. The
+platform doesn't accept batch creates or batch updates on
+the standard CRUD endpoints. Some ingestion-side paths
+(data-activation-client bulk runs, file uploads) ARE batch
+by design — those are documented in the relevant resource's
+MD.

package/.agent/templates.md

@@ -0,0 +1,98 @@
+# Templates
+
+Templates are an **INFRASTRUCTURE** building block: the platform
+ships a library of Liquid templates that other infrastructure
+resources consume — interoperability contracts, AI agent prompts,
+workflow definitions, status poller bodies. Templates are
+**read-only** from the SDK; the platform composes them
+per-industry, and each datalake's `data_domain` selects which
+surface in its catalog.
+
+SDK namespace: `api.templates`.
+
+For the safety contract that bounds every template body the
+platform accepts — the consumer-author trust boundary, the 11
+custom Liquid filters, the SQL-fragment boundary, and the
+compliance gates that compose with them — see `ai_sandbox.md`.
+
+## 1. Wire shape
+
+Three discovery methods, two complementary response shapes —
+structured (for code) and markdown (for agents):
+
+```typescript
+import type { SystemTemplate } from '@alvera-ai/platform-sdk'
+
+// Structured catalog
+const { data: catalog } = await api.templates.systemTemplates(
+  tenantSlug,
+  datalakeSlug,
+)
+// catalog.data: SystemTemplate[]
+//   { path, content, output_schema }
+//     path           category/sub-category/name segment string
+//     content        Liquid template body
+//     output_schema  null | object — rendered output's expected shape
+
+// Markdown catalog
+const { data: catalogMd } = await api.templates.metadata(
+  tenantSlug,
+  datalakeSlug,
+)
+// catalogMd: string — agent-facing markdown listing in-scope templates
+
+// Markdown body for one template
+const { data: templateMd } = await api.templates.metadataDetails(
+  tenantSlug,
+  datalakeSlug,
+  basename,  // e.g. 'delivery_status' or 'contact_message_categorizer'
+  intent,    // e.g. 'status_poller' or 'ai_agent' — note: intent
+             //                                     != path segment;
+             //                                     see §4 Gotcha 1
+)
+// templateMd: string — agent-facing markdown describing the template
+```
+
+## 2. Path structure
+
+Template paths follow `<category>/<sub-category>/<name>`.
+Categories the SDK exposes include
+`data_activation/interoperability/`, `ai_agents/`, `workflows/`,
+`status_poller/`. Categories with an industry segment (e.g.
+`ai_agents/<industry>/*`) filter to the datalake's `data_domain`;
+categories without (e.g. `status_poller/*/*`) are globals
+present in every catalog.
+
+## 3. Lifecycle
+
+Templates are static — they ship with the platform, not created
+via SDK. New templates arrive via platform releases. If you need
+a custom template, supply it inline (e.g. an interop contract's
+`template_config: { type: 'custom', body: '...' }`) rather than
+trying to add to the catalog.
+
+## 4. Gotchas
+
+1. **`basename` + `intent` is the composite key.** The `intent`
+   value is a fixed set of category identifiers — it does NOT
+   map cleanly to path segments. Some intents match (e.g.
+   `status_poller/...` → `'status_poller'`); some are
+   singularizations (e.g. `ai_agents/<industry>/<name>` →
+   `'ai_agent'`); some collapse multiple path segments (e.g.
+   `data_activation/interoperability/<industry>/...` →
+   `'data_activation_interoperability'`). Check the typed
+   parameter for the valid set; multiple templates can share a
+   basename across intents.
+
+2. **`output_schema` may be `null`.** Some templates render plain
+   strings without structured output. Test for null before
+   treating it as an object.
+
+3. **Templates from other industries never appear.** The
+   platform filters per-datalake. Walking the catalog gives only
+   in-scope entries; no need to filter by industry in your code.
+
+4. **Read-only from SDK.** For custom template content, use
+   inline `template_config` on the consuming resource (interop
+   contracts, AI agents, etc.) rather than seeking a catalog
+   addition.

package/.agent/tool-call-configs.md

@@ -0,0 +1,90 @@
+<!-- alvera:doc kind="tool-call-configs" generated-by="mix alvera.dump.static_metadata" -->
+
+# Tool Call Configurations
+
+Per-invocation invocation-side schemas for Alvera tools. Each section
+documents one variant of `Platform.Tools.ToolCallConfig`, identified
+by its atom and rendered by `ToolCallConfig.metadata_details/2`.
+
+<!-- alvera:section kind="tool-call-config" atom="restapi_request" module="Platform.Tools.ToolCallConfig.RESTAPIRequest" -->
+
+## Tool Call Configuration (restapi_request)
+
+Fetches data via REST API with pagination support.
+
+- **method** (enum: head, get, put, post, delete, patch) — HTTP method
+- **path** (TemplateConfig) — API endpoint path, rendered as Liquid template
+- **body** (TemplateConfig, nullable) — Request body, rendered as Liquid template
+- **params** (TemplateConfig, nullable) — Query parameters, rendered as Liquid template
+- **pagination_context_template** (TemplateConfig) — Pagination control template, must render to JSON with `has_next` boolean field
+
+<!-- alvera:section kind="tool-call-config" atom="sql_query" module="Platform.Tools.ToolCallConfig.SQLQuery" -->
+
+## Tool Call Configuration (sql_query)
+
+Fetches data via SQL query with Liquid template variables for pagination.
+
+- **query** (TemplateConfig) — SQL query template with pagination variables
+
+<!-- alvera:section kind="tool-call-config" atom="sftp_request" module="Platform.Tools.ToolCallConfig.SFTPRequest" -->
+
+## Tool Call Configuration (sftp_request)
+
+Fetches data from a remote SFTP server.
+
+- **path** (string) — Remote file path on SFTP server
+- **content_type** (string) — MIME type of the file
+
+<!-- alvera:section kind="tool-call-config" atom="microsoft_share_point_excel_request" module="Platform.Tools.ToolCallConfig.MicrosoftSharePointExcelRequest" -->
+
+## Tool Call Configuration (microsoft_share_point_excel_request)
+
+Fetches data from a Microsoft SharePoint drive (Excel files).
+
+- **drive_url** (string) — SharePoint drive URL
+- **azure_tenant_id** (string) — Microsoft Azure tenant identifier
+- **sheet_number** (integer) — 0-indexed Excel sheet number
+- **search_params** (string) — Search parameters for locating files
+
+<!-- alvera:section kind="tool-call-config" atom="aws_lambda_request" module="Platform.Tools.ToolCallConfig.AWSLambdaRequest" -->
+
+## Tool Call Configuration (aws_lambda_request)
+
+Invokes an AWS Lambda function to fetch data.
+
+- **payload** (TemplateConfig) — Lambda JSON payload, rendered as Liquid template
+- **timeout_ms** (integer, default: 600000, max: 900000) — Invocation timeout in milliseconds
+
+<!-- alvera:section kind="tool-call-config" atom="s3_request" module="Platform.Tools.ToolCallConfig.S3Request" -->
+
+## Tool Call Configuration (s3_request)
+
+Fetches data from an S3 bucket.
+
+- **file_path** (string) — S3 object key (no `s3://` prefix)
+
+<!-- alvera:section kind="tool-call-config" atom="manual_upload" module="Platform.Tools.ToolCallConfig.ManualUpload" -->
+
+## Tool Call Configuration (manual_upload)
+
+Manual file upload — data is uploaded directly by the user. No additional configuration fields.
+
+<!-- alvera:section kind="tool-call-config" atom="sms_request" module="Platform.Tools.ToolCallConfig.SMSRequest" -->
+
+## Tool Call Configuration (sms_request)
+
+Sends an SMS message via the configured SMS provider.
+
+- **to** (TemplateConfig) — Recipient phone number in E.164 format, rendered as Liquid template
+- **body** (TemplateConfig) — Message body, rendered as Liquid template
+- **sms_type** (enum: transactional, promotional) — Message classification; defaults to `transactional`
+
+<!-- alvera:section kind="tool-call-config" atom="email_request" module="Platform.Tools.ToolCallConfig.EmailRequest" -->
+
+## Tool Call Configuration (email_request)
+
+Sends an email message via the configured email provider.
+
+- **to** (TemplateConfig) — Recipient email address (RFC 5322), rendered as Liquid template
+- **subject** (TemplateConfig) — Email subject line, rendered as Liquid template
+- **body** (TemplateConfig) — Email body, rendered as Liquid template