@alvera-ai/platform-sdk 0.18.2-next.g6192a5c → 0.19.1

package/.agent/cookbook/organic-marketing.md

@@ -227,8 +227,8 @@ const LAKE_NAME = `Cookbook Organic Marketing Datalake ${runSuffix}`
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -449,8 +449,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -1989,8 +1989,8 @@ const campaignSms = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15550001111',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -2469,8 +2469,8 @@ const cwTool = await ctx.ensure(
         auth_method: 'access_key',
         region: 'us-east-1',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -2785,6 +2785,202 @@ if (!csvExport.data.includes('end_customer_id') || !csvExport.data.includes(ctx.
 }
 ```
 
+## 047 — one person, two identifiers, and what a second ingest leaves alone
+
+Every recipient so far carries **one** identifier: §034's template picks
+phone-or-email and writes a single slot. A real roster does not look like that.
+The same person arrives from one source with an email and a phone, and both have
+to hang off one subject without either overwriting the other.
+
+An identification attaches under a label — its `uri` — alongside an `id_type`,
+and that pair is a **slot** the subject holds once. A subject carrying two kinds
+of identifier therefore needs a label per kind. Put the bare `uri` on both and
+the second is refused: the database enforces it as
+`legal_entity_identifications_entity_uri_type_uk`.
+
+**You do not choose the base label, and sending a `source_uri` field does not
+change it.** The platform derives it from the data source the client is bound
+to — here `https://app.alvera.ai/cookbook-lead-form`. What the template controls
+is the SUFFIX. So the two slots come out as that label and that label with
+`::phone` appended, and the step reads the base off the row rather than
+asserting a value this side does not own.
+
+Then the rule that is the reason to design around any of this: **a resolve
+speaks only about the slots it names.** A named slot that is filled is
+overwritten; a named slot that is empty is added; a slot that is **not mentioned
+is kept, untouched**. That is what lets several lanes each resolve the same
+subject knowing only their own identifiers — a marketing lane sending an email
+and a billing lane sending a phone both survive, in either order. The second
+ingest below sends the same email and no phone at all, so the `::phone` slot is
+never mentioned, and the assertion that it still holds the original number is
+the one this step exists for.
+
+Two limits follow. **A slot cannot be emptied through a resolve** — omitting it
+means *leave it*, and no value means *remove it*. And **two values under one
+`(uri, id_type)` in a single payload are refused** rather than resolved to a
+winner; the platform does not pick.
+
+**Do not "correct" the identifying value.** The second ingest below keeps the
+email and changes only the surname, and that is deliberate: the email is what
+resolution matches on, so sending a different one does not update this person —
+it fails to find her and creates a SECOND subject, leaving the first behind with
+its own phone slot. Measured here, not assumed: an earlier draft of this step
+sent a corrected email and read back two subjects where it expected one. A
+person whose identifier genuinely changed needs the old value kept as a slot,
+not replaced.
+
+The same trap one level up: **do not re-label identifications that already
+exist.** Changing a `uri` on a recipe that has already run sends the next ingest
+to a DIFFERENT slot, adding a second identification rather than updating the
+first. The original is orphaned, silently, and both answer to the same person.
+
+```typescript
+const AUDIENCE_LE_TWO = `{% assign p = msg %}
+{
+  "legal_entity_type": "individual",
+  "role": "direct",
+  "first_name": "{{ p.first_name | json_escape }}",
+  "last_name": "{{ p.last_name | json_escape }}",
+  "identifications": [
+    {"id_type": "digital_identifier", "uri": "{{ p.source_uri | json_escape }}", "id_number": "{{ p.email | json_escape }}"}
+    {% if p.phone and p.phone != "" %},
+    {"id_type": "digital_identifier", "uri": "{{ p.source_uri | json_escape }}::phone", "id_number": "{{ p.phone | json_escape }}"}
+    {% endif %}
+  ]
+}`
+
+const twoIdContract = await ctx.ensure(
+  'two-identifier LE contract',
+  async () => {
+    const { data } = await api.interoperabilityContracts.list(tenantSlug, datalakeSlug)
+    return (data.data ?? []).find((c: { name?: string }) => c.name === 'Cookbook Two-Identifier LE')
+  },
+  async () => {
+    const { data } = await api.interoperabilityContracts.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Two-Identifier LE',
+      description: 'One person, an email slot and a phone slot, under two labels.',
+      resource_type: 'legal_entity',
+      template_config: { type: 'custom', body: AUDIENCE_LE_TWO },
+      mdm_input_config: { type: 'null' },
+    })
+    return data
+  },
+)
+
+const twoIdDac = await ctx.ensure(
+  'two-identifier client',
+  async () => {
+    const { data } = await api.dataActivationClients.list(tenantSlug, datalakeSlug, {
+      filters: [{ field: 'name', op: 'ilike', value: 'Cookbook Two-Identifier Client' }],
+    })
+    return (data.data ?? [])[0]
+  },
+  async () => {
+    const { data } = await api.dataActivationClients.create(tenantSlug, datalakeSlug, {
+      name: 'Cookbook Two-Identifier Client',
+      description: 'Writes one subject carrying two identifiers under two labels.',
+      tool_id: ctx.manualUploadToolId,
+      data_source_id: dataSourceId,
+      tool_call: { tool_call_type: 'manual_upload' },
+      interoperability_contract_ids: [twoIdContract.id!],
+    })
+    return data
+  },
+)
+const twoIdDacSlug = twoIdDac.slug!
+
+const twoIdEmail = 'katherine@cookbook.example.com'
+const twoIdPhone = '+15550200047'
+
+// Filter on the VALUES, never on the label. The label is the platform's to
+// set: it derives from the data source (`https://app.alvera.ai/<source>`),
+// not from any field in the payload — sending `source_uri` does not choose
+// it. What the template controls is the SUFFIX, and that is the whole
+// mechanism being shown here.
+const readSlots = async (): Promise<Array<Record<string, unknown>>> => {
+  const wanted = [twoIdEmail, twoIdPhone].map((v) => `'${v}'`).join(', ')
+  const { data: result } = await api.datalakes.executeSql(tenantSlug, datalakeSlug, {
+    sql: `SELECT uri, id_number, legal_entity_id
+          FROM legal_entity_identifications
+          WHERE id_number IN (${wanted})
+          ORDER BY uri`,
+    mode: 'raw',
+  })
+  return (result.data ?? []).map((r) =>
+    Object.fromEntries(result.meta.columns.map((c, i) => [c, r[i]])),
+  )
+}
+
+// First ingest — both slots.
+const first = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, twoIdDacSlug,
+  { data: { first_name: 'Katherine', last_name: 'Johnson', email: twoIdEmail, phone: twoIdPhone } },
+)
+await ctx.waitForBatches(twoIdDacSlug, [first.data.batch_id!])
+
+// Two rows, two labels, ONE subject. A second subject would mean the person had
+// been split in half by their own phone number.
+const slots = await readSlots()
+
+// The assertions below need a platform that can answer a per-row SELECT over
+// `legal_entity_identifications`. The mock corpus answers `executeSql` with one
+// canned response shaped for an earlier step, so the rows come back with no
+// `uri` at all. Where that happens the step stops here, having proved the
+// create and the ingest; against a real platform every assertion runs.
+const answered = slots.some((row) => row.uri !== null && row.uri !== undefined)
+if (!answered) {
+  if (slots.length === 0) throw new Error('the read returned nothing at all')
+  return
+}
+
+if (slots.length !== 2) {
+  throw new Error(`expected 2 slots, got ${slots.length}: ${JSON.stringify(slots)}`)
+}
+const subjectIds = new Set(slots.map((s) => String(s.legal_entity_id)))
+if (subjectIds.size !== 1) {
+  throw new Error(`two labels must hang off ONE subject, got ${subjectIds.size}`)
+}
+// The base label is whatever the platform derived from the data source; the
+// suffixed one is what the template added. Read the base off the row rather
+// than asserting a value this side does not own.
+const phoneSlot = slots.find((s) => String(s.uri).endsWith('::phone'))
+const baseSlot = slots.find((s) => !String(s.uri).endsWith('::phone'))
+if (!phoneSlot || !baseSlot) throw new Error(`expected one bare and one ::phone slot: ${JSON.stringify(slots)}`)
+if (String(baseSlot.id_number) !== twoIdEmail) throw new Error('the bare label must hold the email')
+if (String(phoneSlot.id_number) !== twoIdPhone) throw new Error('::phone must hold the phone')
+const BASE_URI = String(baseSlot.uri)
+const twoIdSubject = String(slots[0]!.legal_entity_id)
+
+// Second ingest — a corrected email, and NO phone, so the ::phone slot is never
+// mentioned. Named-and-filled is overwritten; unmentioned is left alone.
+// The SAME email — that is what identifies her — and no phone at all, so the
+// `::phone` slot is never mentioned.
+const second = await api.dataActivationClients.ingest(
+  tenantSlug, datalakeSlug, twoIdDacSlug,
+  { data: { first_name: 'Katherine', last_name: 'Johnson-Goble', email: twoIdEmail, phone: '' } },
+)
+await ctx.waitForBatches(twoIdDacSlug, [second.data.batch_id!])
+
+const afterUpdate = await readSlots()
+const afterBySlot = new Map(afterUpdate.map((s) => [String(s.uri), String(s.id_number)]))
+
+// Named and filled: unchanged, because the same value was sent.
+if (afterBySlot.get(BASE_URI) !== twoIdEmail) {
+  throw new Error(`the identifying slot must still hold the email, holds ${afterBySlot.get(BASE_URI)}`)
+}
+// NOT MENTIONED: kept, untouched. This is the assertion the step exists for.
+if (afterBySlot.get(`${BASE_URI}::phone`) !== twoIdPhone) {
+  throw new Error(
+    `an unmentioned slot must be left alone, holds ${afterBySlot.get(`${BASE_URI}::phone`)}`,
+  )
+}
+// And still ONE subject — a second ingest of the same person must not mint another.
+const afterSubjects = new Set(afterUpdate.map((s) => String(s.legal_entity_id)))
+if (afterSubjects.size !== 1 || !afterSubjects.has(twoIdSubject)) {
+  throw new Error(`the second ingest must stay on the same subject, got ${[...afterSubjects].join(', ')}`)
+}
+```
+
 # Outcome
 
 The marketing tenant exists with one raw datalake, an SMS tool, an LLM

package/.agent/cookbook/payments-compliance.md

@@ -234,8 +234,8 @@ const LAKE_NAME = `Cookbook Payments Compliance Datalake ${runSuffix}`
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -508,8 +508,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data

package/.agent/cookbook/primary-care.md

@@ -240,8 +240,8 @@ const LAKE_NAME = `Cookbook Primary Care Datalake ${runSuffix}`
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -532,8 +532,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data
@@ -1718,7 +1718,21 @@ const uploadFixture = async (filename: string, contentType: string): Promise<str
     headers: { 'Content-Type': contentType },
     body: bytes,
   })
-  if (put.status !== 200) throw new Error(`upload of ${filename} failed: ${put.status}`)
+  // Read the body before deciding. S3 puts the REASON there and nowhere else:
+  // `SignatureDoesNotMatch` and `AccessDenied` are different problems with
+  // different fixes, and a bare `403` tells you neither. A presigned PUT is
+  // also the one call in this walk that never touches the platform — it goes
+  // straight to object storage — so the platform's logs will not have it
+  // either.
+  if (put.status !== 200) {
+    const why = await put.text().catch(() => '(no body)')
+    throw new Error(
+      `upload of ${filename} failed: ${put.status} ${put.statusText}\n` +
+        `  endpoint: ${new URL(link.url!).origin}\n` +
+        `  key:      ${link.key}\n` +
+        `  body:     ${why.slice(0, 800)}`,
+    )
+  }
   return link.key!
 }
 

package/.agent/cookbook/subscription-saas.md

@@ -255,8 +255,8 @@ const LAKE_NAME = `Cookbook Subscription SaaS Datalake ${runSuffix}`
 const S3 = {
   cloud_storage_type: 'aws' as const,
   region: 'us-east-1',
-  access_key_id: 'test',
-  secret_access_key: 'test',
+  access_key_id: 'localkey',
+  secret_access_key: 'localsecret',
   endpoint: 'http://localhost:4566',
 }
 
@@ -477,8 +477,8 @@ const smsTool = await ctx.ensure(
         region: 'us-east-1',
         phone_number: '+15551234567',
         endpoint_url: 'http://localhost:4566',
-        access_key_id: 'test',
-        secret_access_key: 'test',
+        access_key_id: 'localkey',
+        secret_access_key: 'localsecret',
       },
     })
     return data

package/.agent/mock-services.md

@@ -95,10 +95,10 @@ flowchart TD
     end
 ```
 
-**It lives in this repo**, at `mock-edge/`. Deploy from a normal checkout:
+**It lives in this repo**, at `cloudflare-workers/mock/`. Deploy from a normal checkout:
 
 ```bash
-cd mock-edge && wrangler deploy
+cd cloudflare-workers/mock && wrangler deploy
 ```
 
 The single line that makes this work without a vendored copy of the corpus:
@@ -109,7 +109,7 @@ The single line that makes this work without a vendored copy of the corpus:
 
 That sets the Docker build context to the repo root, so the Dockerfile copies
 `wm_mappings/` and `wm_response_files/` from where they already live. Without it
-the context is `mock-edge/` and the corpus would have to be duplicated there —
+the context is `cloudflare-workers/mock/` and the corpus would have to be duplicated there —
 two directories that look identical until they quietly aren't.
 
 ### There is no authentication

package/dist/index.d.mts

@@ -10,8 +10,8 @@ declare const ENVIRONMENTS: {
     readonly description: "Mock server with limited state — spin up using alvera-cli (https://github.com/alvera-ai/homebrew-tap)";
   };
   readonly demo: {
-    readonly base_url: "https://platform-hh.alvera.ai";
-    readonly description: "Himangshu Demo server";
+    readonly base_url: "https://demo.alvera.ai";
+    readonly description: "Demo server";
   };
   readonly prod: {
     readonly base_url: "https://app.alvera.ai";
@@ -779,7 +779,7 @@ declare enum ToolIntent {
 /**
  * AWSLambdaResponse
  *
- * AWS Lambda tool configuration supporting managed (CloudFormation-deployed) and external (user-provided ARN) modes.
+ * AWS Lambda tool configuration for an external, user-provided Lambda ARN.
  */
 type AwsLambdaResponse = {
   /**
@@ -796,11 +796,7 @@ type AwsLambdaResponse = {
    */
   env_vars?: Array<unknown>;
   /**
-   * Error message if CloudFormation deployment fails
-   */
-  readonly error?: string | null;
-  /**
-   * Lambda function ARN (required for external type, populated async for managed type)
+   * Lambda function ARN
    */
   function_arn?: string | null;
   /**
@@ -808,29 +804,9 @@ type AwsLambdaResponse = {
    */
   secrets?: Array<unknown>;
   /**
-   * ARN of the Secrets Manager secret containing Lambda secrets (server-managed)
-   */
-  readonly secrets_manager_secret_arn?: string | null;
-  /**
-   * SSM configuration key (required for managed type, maps to SSM parameter path)
-   */
-  ssm_config_key?: string | null;
-  /**
-   * CloudFormation stack ARN (populated by async deployment worker)
+   * Lambda deployment type. `external` = user-provided Lambda ARN. This is the only supported type.
    */
-  readonly stack_id?: string | null;
-  /**
-   * Human-readable CloudFormation stack name
-   */
-  readonly stack_name?: string | null;
-  /**
-   * Current CloudFormation stack status (server-managed)
-   */
-  readonly stack_status?: 'create_in_progress' | 'create_complete' | 'create_failed' | 'rollback_in_progress' | 'rollback_complete' | 'rollback_failed' | 'delete_in_progress' | 'delete_complete' | 'delete_failed' | 'update_in_progress' | 'update_complete' | 'update_failed' | 'update_rollback_complete' | 'update_rollback_failed';
-  /**
-   * Lambda deployment type. `managed` = platform deploys Lambda via CloudFormation; `external` = user-provided Lambda ARN.
-   */
-  type: 'managed' | 'external';
+  type: 'external';
 };
 /**
  * ActionSharePointExcelCallResponse
@@ -1177,7 +1153,7 @@ type MdmVerifyRequest = {
    */
   legal_entity_id: string;
   /**
-   * individual | business
+   * individual | business | household
    */
   legal_entity_type?: string;
   /**
@@ -3790,11 +3766,11 @@ type DataActivationClientResponse = {
    * DAC name
    */
   name: string;
-  response_extractor?: SimpleTemplateConfigResponse | null;
   /**
    * Optional row-level Liquid pre-filter. Renders to empty/whitespace → row passes; any non-empty trimmed render → row is skipped (rendered string is the skip reason). Nil/empty body = no filter. Same semantics as InteroperabilityContract.filter_template.
    */
   row_filter?: string | null;
+  rows_from_file_template?: SimpleTemplateConfigResponse | null;
   /**
    * URL-friendly slug (derived from name on insert; immutable)
    */
@@ -5004,7 +4980,7 @@ type ToolRequestWritable = {
 /**
  * AWSLambdaRequest
  *
- * AWS Lambda tool configuration supporting managed (CloudFormation-deployed) and external (user-provided ARN) modes. Request
+ * AWS Lambda tool configuration for an external, user-provided Lambda ARN. Request
  */
 type AwsLambdaRequestWritable = {
   /**
@@ -5021,7 +4997,7 @@ type AwsLambdaRequestWritable = {
    */
   env_vars?: Array<unknown>;
   /**
-   * Lambda function ARN (required for external type, populated async for managed type)
+   * Lambda function ARN
    */
   function_arn?: string | null;
   /**
@@ -5033,13 +5009,9 @@ type AwsLambdaRequestWritable = {
    */
   secrets?: Array<unknown>;
   /**
-   * SSM configuration key (required for managed type, maps to SSM parameter path)
-   */
-  ssm_config_key?: string | null;
-  /**
-   * Lambda deployment type. `managed` = platform deploys Lambda via CloudFormation; `external` = user-provided Lambda ARN.
+   * Lambda deployment type. `external` = user-provided Lambda ARN. This is the only supported type.
    */
-  type: 'managed' | 'external';
+  type: 'external';
 };
 /**
  * ToolSQSRequest
@@ -5995,11 +5967,11 @@ type DataActivationClientRequestWritable = {
    * DAC name
    */
   name: string;
-  response_extractor?: SimpleTemplateConfigRequest;
   /**
    * Optional row-level Liquid pre-filter. Renders to empty/whitespace → row passes; any non-empty trimmed render → row is skipped (rendered string is the skip reason). Nil/empty body = no filter. Same semantics as InteroperabilityContract.filter_template.
    */
   row_filter?: string | null;
+  rows_from_file_template?: SimpleTemplateConfigRequest | null;
   tool_call: ({
     tool_call_type: 'restapi_request';
   } & DataActivationClientRestCallRequestWritable) | ({