@linqapp/sdk 0.22.1 → 0.24.0

package/resources/attachments.d.ts

@@ -64,6 +64,122 @@ import { RequestOptions } from "../internal/request-options.js";
  *
  * - **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 declare class Attachments extends APIResource {
     /**
@@ -151,8 +267,10 @@ export declare class Attachments extends APIResource {
      */
     create(body: AttachmentCreateParams, options?: RequestOptions): APIPromise<AttachmentCreateResponse>;
     /**
-     * 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
@@ -162,6 +280,17 @@ export declare class Attachments extends APIResource {
      * ```
      */
     retrieve(attachmentID: string, options?: RequestOptions): APIPromise<AttachmentRetrieveResponse>;
+    /**
+     * 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>;
 }
 /**
  * Supported MIME types for file attachments and media URLs.
@@ -206,8 +335,7 @@ export declare class Attachments extends APIResource {
 export type SupportedContentType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/heic' | 'image/heif' | 'image/tiff' | 'image/bmp' | 'image/svg+xml' | 'image/webp' | 'image/x-icon' | 'video/mp4' | 'video/quicktime' | 'video/mpeg' | 'video/mpeg2' | 'video/x-m4v' | 'video/x-msvideo' | 'video/3gpp' | 'audio/mpeg' | 'audio/mp3' | 'audio/x-m4a' | 'audio/mp4' | 'audio/x-caf' | 'audio/x-wav' | 'audio/x-aiff' | 'audio/aiff' | 'audio/aac' | 'audio/midi' | 'audio/amr' | 'application/pdf' | 'text/plain' | 'text/markdown' | 'text/vcard' | 'text/rtf' | 'text/csv' | 'text/html' | 'text/calendar' | 'application/msword' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.ms-excel' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'application/vnd.ms-powerpoint' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/x-iwork-pages-sffpages' | 'application/x-iwork-numbers-sffnumbers' | 'application/x-iwork-keynote-sffkey' | 'application/epub+zip' | 'text/xml' | 'application/json' | 'application/zip' | 'application/x-gzip';
 export interface AttachmentCreateResponse {
     /**
-     * Unique identifier for the attachment (for status checks via GET
-     * /v3/attachments/{id})
+     * Unique identifier for the attachment
      */
     attachment_id: string;
     /**
@@ -296,7 +424,7 @@ export interface AttachmentRetrieveResponse {
      */
     size_bytes: number;
     /**
-     * Current upload/processing status
+     * @deprecated status is no longer a useful signal
      */
     status: 'pending' | 'complete' | 'failed';
     /**

package/resources/attachments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/resources/attachments.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../src/resources/attachments.ts"],"names":[],"mappings":"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"}

package/resources/attachments.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Attachments = void 0;
 const resource_1 = require("../core/resource.js");
+const headers_1 = require("../internal/headers.js");
 const path_1 = require("../internal/utils/path.js");
 /**
  * Send files (images, videos, documents, audio) with messages by providing a URL in a media part.
@@ -67,6 +68,122 @@ const path_1 = require("../internal/utils/path.js");
  *
  * - **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.
  */
 class Attachments extends resource_1.APIResource {
     /**
@@ -156,8 +273,10 @@ class Attachments extends resource_1.APIResource {
         return this._client.post('/v3/attachments', { body, ...options });
     }
     /**
-     * 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
@@ -169,6 +288,22 @@ class Attachments extends resource_1.APIResource {
     retrieve(attachmentID, options) {
         return this._client.get((0, path_1.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, options) {
+        return this._client.delete((0, path_1.path) `/v3/attachments/${attachmentID}`, {
+            ...options,
+            headers: (0, headers_1.buildHeaders)([{ Accept: '*/*' }, options?.headers]),
+        });
+    }
 }
 exports.Attachments = Attachments;
 //# sourceMappingURL=attachments.js.map

package/resources/attachments.js.map

@@ -1 +1 @@
-{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../src/resources/attachments.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAG/C,oDAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAa,WAAY,SAAQ,sBAAW;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkFG;IACH,MAAM,CAAC,IAA4B,EAAE,OAAwB;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAoB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,mBAAmB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;CACF;AAtGD,kCAsGC"}
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../src/resources/attachments.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAE/C,oDAAmD;AAEnD,oDAA8C;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmLG;AACH,MAAa,WAAY,SAAQ,sBAAW;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkFG;IACH,MAAM,CAAC,IAA4B,EAAE,OAAwB;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAoB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,mBAAmB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAoB,EAAE,OAAwB;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAA,WAAI,EAAA,mBAAmB,YAAY,EAAE,EAAE;YAChE,GAAG,OAAO;YACV,OAAO,EAAE,IAAA,sBAAY,EAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF;AAzHD,kCAyHC"}

package/resources/attachments.mjs

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 import { APIResource } from "../core/resource.mjs";
+import { buildHeaders } from "../internal/headers.mjs";
 import { path } from "../internal/utils/path.mjs";
 /**
  * Send files (images, videos, documents, audio) with messages by providing a URL in a media part.
@@ -64,6 +65,122 @@ import { path } from "../internal/utils/path.mjs";
  *
  * - **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 {
     /**
@@ -153,8 +270,10 @@ export class Attachments extends APIResource {
         return this._client.post('/v3/attachments', { body, ...options });
     }
     /**
-     * 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
@@ -166,5 +285,21 @@ export class Attachments extends APIResource {
     retrieve(attachmentID, options) {
         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, options) {
+        return this._client.delete(path `/v3/attachments/${attachmentID}`, {
+            ...options,
+            headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+        });
+    }
 }
 //# sourceMappingURL=attachments.mjs.map

package/resources/attachments.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"attachments.mjs","sourceRoot":"","sources":["../src/resources/attachments.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAGf,EAAE,IAAI,EAAE;AAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,OAAO,WAAY,SAAQ,WAAW;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkFG;IACH,MAAM,CAAC,IAA4B,EAAE,OAAwB;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAoB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,mBAAmB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;CACF"}
+{"version":3,"file":"attachments.mjs","sourceRoot":"","sources":["../src/resources/attachments.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAEf,EAAE,YAAY,EAAE;OAEhB,EAAE,IAAI,EAAE;AAEf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmLG;AACH,MAAM,OAAO,WAAY,SAAQ,WAAW;IAC1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkFG;IACH,MAAM,CAAC,IAA4B,EAAE,OAAwB;QAC3D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAoB,EAAE,OAAwB;QACrD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,mBAAmB,YAAY,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,YAAoB,EAAE,OAAwB;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAA,mBAAmB,YAAY,EAAE,EAAE;YAChE,GAAG,OAAO;YACV,OAAO,EAAE,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;SAC7D,CAAC,CAAC;IACL,CAAC;CACF"}

package/resources/chats/chats.d.mts

@@ -243,9 +243,9 @@ export interface Chat {
      */
     handles: Array<Shared.ChatHandle>;
     /**
-     * **[BETA]** Current health for a chat. Always present — chats start at `healthy`
+     * **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY`
      * and may shift based on engagement and delivery signals on the conversation. Many
-     * `at_risk` or `critical` chats on a single line increase the risk of line
+     * `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line
      * flagging.
      *
      * Switch on `status` to gate sends or surface line health in your UI — the enum is
@@ -257,7 +257,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;
     /**
@@ -275,9 +275,9 @@ export interface Chat {
 }
 export declare namespace Chat {
     /**
-     * **[BETA]** Current health for a chat. Always present — chats start at `healthy`
+     * **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY`
      * and may shift based on engagement and delivery signals on the conversation. Many
-     * `at_risk` or `critical` chats on a single line increase the risk of line
+     * `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line
      * flagging.
      *
      * Switch on `status` to gate sends or surface line health in your UI — the enum is
@@ -297,7 +297,7 @@ export declare namespace Chat {
          * [Chat Health guide](/guides/chats/chat-health) for what each value means and how
          * to react. `doc_url` deep-links to the relevant section.
          */
-        status: 'healthy' | 'at_risk' | 'critical' | 'opted_out';
+        status: 'HEALTHY' | 'AT_RISK' | 'CRITICAL' | 'OPTED_OUT';
         /**
          * When this status last changed.
          */
@@ -482,9 +482,9 @@ export declare namespace ChatCreateResponse {
          */
         handles: Array<Shared.ChatHandle>;
         /**
-         * **[BETA]** Current health for a chat. Always present — chats start at `healthy`
+         * **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY`
          * and may shift based on engagement and delivery signals on the conversation. Many
-         * `at_risk` or `critical` chats on a single line increase the risk of line
+         * `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line
          * flagging.
          *
          * Switch on `status` to gate sends or surface line health in your UI — the enum is
@@ -510,9 +510,9 @@ export declare namespace ChatCreateResponse {
     }
     namespace Chat {
         /**
-         * **[BETA]** Current health for a chat. Always present — chats start at `healthy`
+         * **[BETA]** Current health for a chat. Always present — chats start at `HEALTHY`
          * and may shift based on engagement and delivery signals on the conversation. Many
-         * `at_risk` or `critical` chats on a single line increase the risk of line
+         * `AT_RISK` or `CRITICAL` chats on a single line increase the risk of line
          * flagging.
          *
          * Switch on `status` to gate sends or surface line health in your UI — the enum is
@@ -532,7 +532,7 @@ export declare namespace ChatCreateResponse {
              * [Chat Health guide](/guides/chats/chat-health) for what each value means and how
              * to react. `doc_url` deep-links to the relevant section.
              */
-            status: 'healthy' | 'at_risk' | 'critical' | 'opted_out';
+            status: 'HEALTHY' | 'AT_RISK' | 'CRITICAL' | 'OPTED_OUT';
             /**
              * When this status last changed.
              */