@linqapp/sdk 0.22.0 → 0.23.0

package/src/client.ts

@@ -940,6 +940,122 @@ export class LinqAPIV3 {
    * - **URL-based (`url` field):** 10MB maximum
    * - **Pre-upload (`attachment_id`):** 100MB maximum
    *
+   * ## Security & Ownership
+   *
+   * Every attachment is bound to the partner account that created or received it. The API enforces ownership on every operation that touches an attachment — sending, retrieving, deleting.
+   *
+   * **What this means for you:**
+   *
+   * - An attachment created under your API key can only be referenced by your API key.
+   * - Submitting another partner's `attachment_id` returns `404 Not Found`. We do not disclose whether the id exists or belongs to someone else.
+   * - Submitting a CDN URL that resolves to another partner's attachment is rejected before the send is attempted.
+   * - Ownership enforcement applies uniformly across send, create-chat, voice memo, retrieve, and delete operations.
+   *
+   * Every attachment-affecting endpoint requires a valid partner API key. Unauthenticated calls return `401 Unauthorized`.
+   *
+   * ## Attachment URL Patterns
+   *
+   * Attachment URLs in API responses and webhook payloads use one of two layouts, depending on the attachment's tier:
+   *
+   * | Tier | URL pattern | TTL |
+   * |---|---|---|
+   * | Persistent (default) | `https://cdn.linqapp.com/attachments/partners/{partner_id}/{attachment_id}/{filename}` | Long-lived |
+   * | Ephemeral | Pre-signed URL pointing at the ephemeral prefix on `cdn.linqapp.com` | 15 minutes per signed URL — re-fetch via the API for a fresh URL |
+   *
+   * Inbound media you receive over webhooks uses the same layout your outbound sends produce, so the URL you store and the URL you build look identical — no special casing in your client.
+   *
+   * ## Ephemeral Attachments (Privacy Tier)
+   *
+   * For regulated or sensitive content, opt in to the **ephemeral attachments** tier by contacting your Linq support contact. You can request it at two scopes:
+   *
+   * | Scope | Effect |
+   * |---|---|
+   * | **Partner-wide** | Every outbound and inbound attachment on every phone number under your account is routed through the ephemeral tier. |
+   * | **Per phone number** | Only the specified phone numbers route their attachments through the ephemeral tier. The rest stay on the persistent tier. |
+   *
+   * **Behavioral differences vs the persistent default:**
+   *
+   * | Aspect | Persistent | Ephemeral |
+   * |---|---|---|
+   * | Download URL form | Long-lived CDN URL | Pre-signed URL with short TTL |
+   * | Retention floor | Indefinite (until you call `DELETE`) | **Hard backstop: 1 day** — even without an explicit `DELETE`, the platform removes the underlying bytes after 24 hours |
+   * | URL re-fetch | Not required | Fetch via `GET /v3/attachments/{attachmentId}` for a fresh signed URL after TTL expiry |
+   * | Cross-partner isolation | Enforced | Enforced |
+   *
+   * **When to choose ephemeral:**
+   *
+   * - Your downstream system processes the file immediately on receipt and does not need to re-read it later.
+   * - You have a compliance requirement that the platform must not retain attachments beyond a short window.
+   * - The content is high-sensitivity (PHI, financial documents, identity verification) and you do not want it sitting behind a long-lived URL.
+   *
+   * **Important:** ephemeral applies in *both directions* — outbound files you upload **and** inbound media received by the phone numbers in that scope. Download bytes you need to keep promptly, or fetch a fresh signed URL via the API when needed.
+   *
+   * ## Deleting an Attachment
+   *
+   * To permanently remove an attachment you own, use:
+   *
+   * ```http
+   * DELETE /v3/attachments/{attachmentId}
+   * Authorization: Bearer <your_api_key>
+   * ```
+   *
+   * **What this does:**
+   *
+   * 1. Verifies the attachment is owned by your account. Returns `404` otherwise.
+   * 2. Removes the underlying file from Linq storage.
+   * 3. Records an audit entry (timestamp, partner, attachment id).
+   *
+   * **Response codes:**
+   *
+   * | Status | Meaning |
+   * |---|---|
+   * | `204 No Content` | Deletion succeeded. The attachment is removed from Linq storage. |
+   * | `400 Bad Request` | `attachmentId` is not a valid UUID. |
+   * | `401 Unauthorized` | Missing or invalid API key. |
+   * | `404 Not Found` | Attachment does not exist or is not owned by your account. |
+   * | `500 Internal Server Error` | Transient infrastructure issue — safe to retry. |
+   *
+   * **Effect on message history:**
+   *
+   * - Messages that referenced the deleted attachment remain visible.
+   * - The message part that pointed at the attachment is preserved with no attachment reference.
+   * - Webhook payloads previously delivered to you retain the original URL string, but downloads from that URL return `404` going forward.
+   *
+   * Deletion is **irreversible**. Once `204` is returned, the bytes are gone — there is no undelete.
+   *
+   * ## Inbound Media Flow
+   *
+   * When one of your phone numbers receives a message with media (image, video, audio, document), the platform:
+   *
+   * 1. Stores the file under your partner account.
+   * 2. Records metadata linked to the inbound message.
+   * 3. Delivers a webhook whose `parts[]` array includes a `media` part with a `url` pointing at `cdn.linqapp.com`.
+   * 4. If the receiving phone is opted in to ephemeral, the `url` is a short-TTL signed URL.
+   *
+   * You can acknowledge the webhook without fetching the file inline, and lazy-load via `GET /v3/attachments/{attachmentId}` later. For ephemeral attachments, retrieving via the API always returns a freshly-signed URL.
+   *
+   * ## Data Lifecycle Summary
+   *
+   * | Data | Persistent tier | Ephemeral tier |
+   * |---|---|---|
+   * | Attachment bytes | Retained until you `DELETE` | **Auto-removed after 1 day**, also removable via `DELETE` |
+   * | Attachment metadata (id, filename, mime type, size) | Retained until you `DELETE` | Removed alongside the bytes |
+   * | Message body & parts | Retained per message-retention policy | Retained per message-retention policy |
+   * | Audit log of deletions | Retained per platform retention policy | Retained per platform retention policy |
+   *
+   * **In transit:** TLS 1.2+ everywhere. **At rest:** AES-256 (server-side encryption).
+   *
+   * ## Compliance Checklist
+   *
+   * If you're integrating Linq under a security or privacy review, here is the short list:
+   *
+   * - Allowlist exactly one outbound domain: `cdn.linqapp.com`.
+   * - Decide whether you need ephemeral attachments (high-sensitivity content) — request enablement through your Linq support contact.
+   * - Implement `DELETE /v3/attachments/{attachmentId}` calls in your deletion workflow.
+   * - Persist any attachments your application needs long-term — Linq is the authoritative source until you delete, but the ephemeral tier auto-purges after 1 day.
+   * - For audit: every deletion is logged on Linq's side. Surface a confirmation in your application UI based on the `204` response.
+   * - For end-user "right to delete" requests: enumerate attachment ids and `DELETE` each. The platform does not provide a partner-wide wipe endpoint — deletion is per-attachment by design.
+   *
    */
   attachments: API.Attachments = new API.Attachments(this);
   /**

package/src/internal/utils/log.ts

@@ -107,6 +107,8 @@ export const formatRequestDetails = (details: {
           name,
           (
             name.toLowerCase() === 'authorization' ||
+            name.toLowerCase() === 'api-key' ||
+            name.toLowerCase() === 'x-api-key' ||
             name.toLowerCase() === 'cookie' ||
             name.toLowerCase() === 'set-cookie'
           ) ?

package/src/resources/attachments.ts

@@ -2,6 +2,7 @@
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
+import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
@@ -68,6 +69,122 @@ import { path } from '../internal/utils/path';
  *
  * - **URL-based (`url` field):** 10MB maximum
  * - **Pre-upload (`attachment_id`):** 100MB maximum
+ *
+ * ## Security & Ownership
+ *
+ * Every attachment is bound to the partner account that created or received it. The API enforces ownership on every operation that touches an attachment — sending, retrieving, deleting.
+ *
+ * **What this means for you:**
+ *
+ * - An attachment created under your API key can only be referenced by your API key.
+ * - Submitting another partner's `attachment_id` returns `404 Not Found`. We do not disclose whether the id exists or belongs to someone else.
+ * - Submitting a CDN URL that resolves to another partner's attachment is rejected before the send is attempted.
+ * - Ownership enforcement applies uniformly across send, create-chat, voice memo, retrieve, and delete operations.
+ *
+ * Every attachment-affecting endpoint requires a valid partner API key. Unauthenticated calls return `401 Unauthorized`.
+ *
+ * ## Attachment URL Patterns
+ *
+ * Attachment URLs in API responses and webhook payloads use one of two layouts, depending on the attachment's tier:
+ *
+ * | Tier | URL pattern | TTL |
+ * |---|---|---|
+ * | Persistent (default) | `https://cdn.linqapp.com/attachments/partners/{partner_id}/{attachment_id}/{filename}` | Long-lived |
+ * | Ephemeral | Pre-signed URL pointing at the ephemeral prefix on `cdn.linqapp.com` | 15 minutes per signed URL — re-fetch via the API for a fresh URL |
+ *
+ * Inbound media you receive over webhooks uses the same layout your outbound sends produce, so the URL you store and the URL you build look identical — no special casing in your client.
+ *
+ * ## Ephemeral Attachments (Privacy Tier)
+ *
+ * For regulated or sensitive content, opt in to the **ephemeral attachments** tier by contacting your Linq support contact. You can request it at two scopes:
+ *
+ * | Scope | Effect |
+ * |---|---|
+ * | **Partner-wide** | Every outbound and inbound attachment on every phone number under your account is routed through the ephemeral tier. |
+ * | **Per phone number** | Only the specified phone numbers route their attachments through the ephemeral tier. The rest stay on the persistent tier. |
+ *
+ * **Behavioral differences vs the persistent default:**
+ *
+ * | Aspect | Persistent | Ephemeral |
+ * |---|---|---|
+ * | Download URL form | Long-lived CDN URL | Pre-signed URL with short TTL |
+ * | Retention floor | Indefinite (until you call `DELETE`) | **Hard backstop: 1 day** — even without an explicit `DELETE`, the platform removes the underlying bytes after 24 hours |
+ * | URL re-fetch | Not required | Fetch via `GET /v3/attachments/{attachmentId}` for a fresh signed URL after TTL expiry |
+ * | Cross-partner isolation | Enforced | Enforced |
+ *
+ * **When to choose ephemeral:**
+ *
+ * - Your downstream system processes the file immediately on receipt and does not need to re-read it later.
+ * - You have a compliance requirement that the platform must not retain attachments beyond a short window.
+ * - The content is high-sensitivity (PHI, financial documents, identity verification) and you do not want it sitting behind a long-lived URL.
+ *
+ * **Important:** ephemeral applies in *both directions* — outbound files you upload **and** inbound media received by the phone numbers in that scope. Download bytes you need to keep promptly, or fetch a fresh signed URL via the API when needed.
+ *
+ * ## Deleting an Attachment
+ *
+ * To permanently remove an attachment you own, use:
+ *
+ * ```http
+ * DELETE /v3/attachments/{attachmentId}
+ * Authorization: Bearer <your_api_key>
+ * ```
+ *
+ * **What this does:**
+ *
+ * 1. Verifies the attachment is owned by your account. Returns `404` otherwise.
+ * 2. Removes the underlying file from Linq storage.
+ * 3. Records an audit entry (timestamp, partner, attachment id).
+ *
+ * **Response codes:**
+ *
+ * | Status | Meaning |
+ * |---|---|
+ * | `204 No Content` | Deletion succeeded. The attachment is removed from Linq storage. |
+ * | `400 Bad Request` | `attachmentId` is not a valid UUID. |
+ * | `401 Unauthorized` | Missing or invalid API key. |
+ * | `404 Not Found` | Attachment does not exist or is not owned by your account. |
+ * | `500 Internal Server Error` | Transient infrastructure issue — safe to retry. |
+ *
+ * **Effect on message history:**
+ *
+ * - Messages that referenced the deleted attachment remain visible.
+ * - The message part that pointed at the attachment is preserved with no attachment reference.
+ * - Webhook payloads previously delivered to you retain the original URL string, but downloads from that URL return `404` going forward.
+ *
+ * Deletion is **irreversible**. Once `204` is returned, the bytes are gone — there is no undelete.
+ *
+ * ## Inbound Media Flow
+ *
+ * When one of your phone numbers receives a message with media (image, video, audio, document), the platform:
+ *
+ * 1. Stores the file under your partner account.
+ * 2. Records metadata linked to the inbound message.
+ * 3. Delivers a webhook whose `parts[]` array includes a `media` part with a `url` pointing at `cdn.linqapp.com`.
+ * 4. If the receiving phone is opted in to ephemeral, the `url` is a short-TTL signed URL.
+ *
+ * You can acknowledge the webhook without fetching the file inline, and lazy-load via `GET /v3/attachments/{attachmentId}` later. For ephemeral attachments, retrieving via the API always returns a freshly-signed URL.
+ *
+ * ## Data Lifecycle Summary
+ *
+ * | Data | Persistent tier | Ephemeral tier |
+ * |---|---|---|
+ * | Attachment bytes | Retained until you `DELETE` | **Auto-removed after 1 day**, also removable via `DELETE` |
+ * | Attachment metadata (id, filename, mime type, size) | Retained until you `DELETE` | Removed alongside the bytes |
+ * | Message body & parts | Retained per message-retention policy | Retained per message-retention policy |
+ * | Audit log of deletions | Retained per platform retention policy | Retained per platform retention policy |
+ *
+ * **In transit:** TLS 1.2+ everywhere. **At rest:** AES-256 (server-side encryption).
+ *
+ * ## Compliance Checklist
+ *
+ * If you're integrating Linq under a security or privacy review, here is the short list:
+ *
+ * - Allowlist exactly one outbound domain: `cdn.linqapp.com`.
+ * - Decide whether you need ephemeral attachments (high-sensitivity content) — request enablement through your Linq support contact.
+ * - Implement `DELETE /v3/attachments/{attachmentId}` calls in your deletion workflow.
+ * - Persist any attachments your application needs long-term — Linq is the authoritative source until you delete, but the ephemeral tier auto-purges after 1 day.
+ * - For audit: every deletion is logged on Linq's side. Surface a confirmation in your application UI based on the `204` response.
+ * - For end-user "right to delete" requests: enumerate attachment ids and `DELETE` each. The platform does not provide a partner-wide wipe endpoint — deletion is per-attachment by design.
  */
 export class Attachments extends APIResource {
   /**
@@ -158,8 +275,10 @@ export class Attachments extends APIResource {
   }
 
   /**
-   * Retrieve metadata for a specific attachment including its status, file
-   * information, and URLs for downloading.
+   * Retrieve metadata for a specific attachment including file information, and URLs
+   * for downloading.
+   *
+   * `status`: (**deprecated** — will be removed in a future API version)
    *
    * @example
    * ```ts
@@ -171,6 +290,23 @@ export class Attachments extends APIResource {
   retrieve(attachmentID: string, options?: RequestOptions): APIPromise<AttachmentRetrieveResponse> {
     return this._client.get(path`/v3/attachments/${attachmentID}`, options);
   }
+
+  /**
+   * Permanently delete an attachment owned by the authenticated partner.
+   *
+   * @example
+   * ```ts
+   * await client.attachments.delete(
+   *   'abc12345-1234-5678-9abc-def012345678',
+   * );
+   * ```
+   */
+  delete(attachmentID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v3/attachments/${attachmentID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
 }
 
 /**
@@ -267,8 +403,7 @@ export type SupportedContentType =
 
 export interface AttachmentCreateResponse {
   /**
-   * Unique identifier for the attachment (for status checks via GET
-   * /v3/attachments/{id})
+   * Unique identifier for the attachment
    */
   attachment_id: string;
 
@@ -366,7 +501,7 @@ export interface AttachmentRetrieveResponse {
   size_bytes: number;
 
   /**
-   * Current upload/processing status
+   * @deprecated status is no longer a useful signal
    */
   status: 'pending' | 'complete' | 'failed';
 

package/src/resources/chats/chats.ts

@@ -312,7 +312,7 @@ export interface Chat {
   health_status: Chat.HealthStatus;
 
   /**
-   * Whether the chat is archived
+   * @deprecated is_archived is no longer a useful signal
    */
   is_archived: boolean;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.22.0'; // x-release-please-version
+export const VERSION = '0.23.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.22.0";
+export declare const VERSION = "0.23.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.22.0";
+export declare const VERSION = "0.23.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.22.0'; // x-release-please-version
+exports.VERSION = '0.23.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.22.0'; // x-release-please-version
+export const VERSION = '0.23.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map