@messagebird/sdk 0.37.2 → 0.38.0

package/dist/index.mjs

@@ -1654,6 +1654,112 @@ const updateContact = (options) => (options.client ?? client).patch({
 	}
 });
 /**
+* List a contact's preferences
+*
+* Returns the preferences on record for the contact's current handles: rows keyed to their email address on the email channel, and to their phone number on SMS and WhatsApp. A contact with no handles, or with no statements on record, returns an empty page.
+*
+* Rows are keyed by handle, not by contact: changing a contact's email address or phone number changes which rows this returns, and the old handle's rows remain in force for anything still sent to it.
+*
+*/
+const listContactPreferences = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/contacts/{contact_id}/preferences",
+	...options
+});
+/**
+* List preferences
+*
+* Returns the workspace's recorded preferences, most recently created first. Pass `channel` to narrow to one channel, and `handle` with it to look up everything on record for one address or number.
+*
+* Each row is a key's current statement. A person can hold several rows on one channel (a channel-wide opt-out next to sender-scoped ones), and the most restrictive statement is what decides whether a message goes out.
+*
+*/
+const listPreferences = (options) => (options?.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/preferences",
+	...options
+});
+/**
+* Record a preference
+*
+* Records one statement, a grant or an opt-out, for a handle on one channel. Writing is an upsert: the key is the channel, handle, and optional sender scope, and a new statement replaces the key's current one.
+*
+* Statements are ordered by when they were made, not when they arrive. A statement older than the key's current one is refused and returned with `applied: false` alongside the statement that survived; refusals are recorded on the key's history. Granting over a stored opt-out needs `consented_at` later than the opt-out, and a person's own opt-out (an unsubscribe, a stop keyword) cannot be overridden by a grant asserted on their behalf.
+*
+* A `201` means this key had no record and one was created; a `200` returns the key's surviving record, whether this statement replaced it, repeated it, or was refused.
+*
+*/
+const createPreference = (options) => (options.client ?? client).post({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/preferences",
+	...options,
+	headers: {
+		"Content-Type": "application/json",
+		...options.headers
+	}
+});
+/**
+* Delete a preference
+*
+* Deletes a preference, returning its key to having no record, as if nothing had ever been stated. The deletion itself is kept on the key's history, so a later statement is still ordered against what was deleted.
+*
+* **A statement the person made themselves cannot be deleted.** An unsubscribe or a stop keyword is their statement to reverse: it ends when they opt back in, and attempts to delete it return `422`. To restore messaging with the person's consent, record a `granted` statement with `consented_at` evidence instead; that records the change of mind rather than erasing the opt-out.
+*
+* A delete is ordered like any statement, using the time it is received: if the record carries a statement made after that moment, the delete is refused and returned with `applied: false` alongside the surviving record. An ID that does not exist in the workspace returns `404`.
+*
+*/
+const deletePreference = (options) => (options.client ?? client).delete({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/preferences/{preference_id}",
+	...options
+});
+/**
+* Get a preference
+*
+* Returns one preference: the key it is about, the current statement on it, and the statement's provenance. An ID that does not exist in the workspace returns `404`, including after a delete, which removes the record its ID pointed at.
+*
+*/
+const getPreference = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}, {
+		in: "cookie",
+		name: "bird_session",
+		type: "apiKey"
+	}],
+	url: "/v1/preferences/{preference_id}",
+	...options
+});
+/**
 * List contact properties
 *
 * Returns a paginated list of the workspace's contact properties, newest first. Archived properties are included; check each entry's `archived` flag.
@@ -5417,7 +5523,7 @@ var ContactPropertiesResource = class extends Resource {
 };
 //#endregion
 //#region src/resources/contacts.gen.ts
-var ContactsResource = class extends Resource {
+var ContactsResourceBase = class extends Resource {
 	/**
 	* List the workspace's contacts as a cursor page, newest first. Look one up by exact email, phone_number, or external_id, repeating phone_number to resolve up to 50 numbers in one call (raise limit to match), or search by email, name, or phone substring. Pass include_total for a total count.
 	*
@@ -5524,6 +5630,138 @@ var ContactsResource = class extends Resource {
 	}
 };
 //#endregion
+//#region src/resources/contactsPreferences.gen.ts
+var ContactsPreferencesResource = class extends Resource {
+	/**
+	* List the recorded messaging preferences for a contact's own handles (their email address and phone number) across every channel, as a cursor page.
+	*
+	* @example List a contact's own preferences
+	* for await (const preference of bird.contacts.preferences.list(
+	*   "con_01krdgeqcxet5s7t44vh8rt9mg",
+	* )) {
+	*   console.log(preference.channel, preference.status);
+	* }
+	*/
+	list(contactId, query, options) {
+		return this.paginated("GET", options, ({ signal, headers }, cursor) => listContactPreferences({
+			client: this.client,
+			path: { contact_id: contactId },
+			query: {
+				...query,
+				starting_after: cursor ?? query?.starting_after
+			},
+			headers,
+			signal
+		}));
+	}
+};
+//#endregion
+//#region src/resources/contacts.ts
+var ContactsResource = class extends ContactsResourceBase {
+	/** A contact's own preferences across every channel — `bird.contacts.preferences.list(contactId)`. */
+	preferences;
+	constructor(core, client) {
+		super(core, client);
+		this.preferences = new ContactsPreferencesResource(core, client);
+	}
+};
+//#endregion
+//#region src/resources/preferences.gen.ts
+var PreferencesResourceBase = class extends Resource {
+	/**
+	* List the workspace's stated messaging preferences (consent grants and opt-outs) as a cursor page. Filter by channel, and by handle within a channel, to look up one person before messaging them.
+	*
+	* @example List stated preferences for a channel
+	* for await (const preference of bird.preferences.list({ channel: "sms" })) {
+	*   console.log(preference.handle, preference.status);
+	* }
+	*/
+	list(query, options) {
+		return this.paginated("GET", options, ({ signal, headers }, cursor) => listPreferences({
+			client: this.client,
+			query: {
+				...query,
+				starting_after: cursor ?? query?.starting_after
+			},
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Read one recorded preference by ID: the channel and handle it is about, whether it grants or revokes, how much traffic it covers, and where the statement came from.
+	*
+	* @example Read one preference
+	* const preference = await bird.preferences.get(
+	*   "prf_01krdgeqcxet5s7t44vh8rt9mg",
+	* );
+	* console.log(preference.status, preference.coverage);
+	*/
+	get(preferenceId, options) {
+		return this.call("GET", options, ({ signal, headers }) => getPreference({
+			client: this.client,
+			path: { preference_id: preferenceId },
+			headers,
+			signal
+		}));
+	}
+};
+//#endregion
+//#region src/resources/preferences.ts
+var PreferencesResource = class extends PreferencesResourceBase {
+	/**
+	* Record one preference statement — a grant or an opt-out — for a handle on
+	* one channel. Writing is an upsert by key (channel, handle, and optional
+	* sender scope): statements are causally ordered, so one dated older than
+	* the key's current statement is refused and returned with `applied:
+	* false` rather than applied out of order. A `201` (the key had no record)
+	* and a `200` (the key already had one) return the same shape either way.
+	*
+	* @example Record a stated opt-out
+	* const result = await bird.preferences.create({
+	*   channel: "sms",
+	*   handle: "+15550001234",
+	*   status: "revoked",
+	* });
+	* console.log(result.applied, result.preference?.id);
+	*/
+	create(params, options) {
+		const { consented_at, ...rest } = params;
+		const body = consented_at === void 0 ? rest : {
+			...rest,
+			consented_at: consented_at instanceof Date ? consented_at.toISOString() : consented_at
+		};
+		return this.call("POST", options, ({ signal, headers }) => createPreference({
+			client: this.client,
+			body,
+			headers,
+			signal
+		}));
+	}
+	/**
+	* Delete a preference, returning its key to having no record. Never void:
+	* the delete is ordered like any statement, so a `200` with `applied:
+	* false` means a newer statement survived and is returned in `preference`
+	* rather than deleted. A statement the person made themselves — an
+	* unsubscribe link, a stop keyword — cannot be deleted this way; record a
+	* `granted` statement with `consented_at` evidence to restore messaging
+	* instead.
+	*
+	* @example Delete a preference
+	* const result = await bird.preferences.delete("prf_01krdgeqcxet5s7t44vh8rt9mg");
+	* if (!result.applied) {
+	*   console.log("refused — a newer statement survived:", result.preference?.status);
+	* }
+	*/
+	delete(preferenceId, options) {
+		return this.call("DELETE", options, ({ signal, headers }) => deletePreference({
+			client: this.client,
+			path: { preference_id: preferenceId },
+			headers,
+			signal
+		}));
+	}
+};
+//#endregion
 //#region src/resources/sms.gen.ts
 var SmsResourceBase = class extends Resource {
 	/**
@@ -7111,6 +7349,8 @@ var BirdClient = class {
 	verify;
 	/** Contacts: `bird.contacts.create(...)`, `.list(...)`, `.get(...)`, `.batch(...)`, … */
 	contacts;
+	/** Preferences: `bird.preferences.list(...)`, `.get(...)`, `.create(...)`, `.delete(...)`. */
+	preferences;
 	/** Audiences: `bird.audiences.create(...)`, `.list(...)`, `.addContacts(...)`, … */
 	audiences;
 	/** Contact properties: `bird.contactProperties.create(...)`, `.list(...)`, `.archive(...)`, … */
@@ -7132,9 +7372,9 @@ var BirdClient = class {
 		this.#headers = {
 			...opts.defaultHeaders,
 			Authorization: `Bearer ${opts.apiKey}`,
-			"User-Agent": `bird-sdk-js/0.37.2`,
+			"User-Agent": `bird-sdk-js/0.38.0`,
 			"Bird-Surface": "sdk-js",
-			"Bird-Version": "0.37.2"
+			"Bird-Version": "0.38.0"
 		};
 		const caller = detectCaller();
 		if (caller) this.#headers["Bird-Caller"] = caller;
@@ -7168,6 +7408,7 @@ var BirdClient = class {
 		this.voice = new VoiceResource(this.core, this.#client);
 		this.verify = new VerifyResource(this.core, this.#client);
 		this.contacts = new ContactsResource(this.core, this.#client);
+		this.preferences = new PreferencesResource(this.core, this.#client);
 		this.audiences = new AudiencesResource(this.core, this.#client);
 		this.contactProperties = new ContactPropertiesResource(this.core, this.#client);
 		this.domains = new DomainsResource(this.core, this.#client);
@@ -7258,6 +7499,9 @@ const WebhookEventType = {
 	EmailScheduled: "email.scheduled",
 	EmailSuppressionCreated: "email_suppression.created",
 	EmailUnsubscribed: "email.unsubscribed",
+	PreferenceDeleted: "preference.deleted",
+	PreferenceGranted: "preference.granted",
+	PreferenceRevoked: "preference.revoked",
 	SmsAccepted: "sms.accepted",
 	SmsDelivered: "sms.delivered",
 	SmsExpired: "sms.expired",
@@ -7282,7 +7526,8 @@ const WebhookEventType = {
 	WhatsappRead: "whatsapp.read",
 	WhatsappReceived: "whatsapp.received",
 	WhatsappRejected: "whatsapp.rejected",
-	WhatsappSent: "whatsapp.sent"
+	WhatsappSent: "whatsapp.sent",
+	WhatsappSuppressionCreated: "whatsapp_suppression.created"
 };
 //#endregion
 //#region src/open-enums.gen.ts
@@ -7391,6 +7636,30 @@ const NumbersOrderStatus = {
 	Pending: "pending"
 };
 /**
+* Values of PreferenceChannel known at this SDK version. The wire value is an open
+* string: a value added by a newer server deserializes unchanged, so switch on
+* these with a `default` branch rather than treating the set as closed.
+*/
+const PreferenceChannel = {
+	Email: "email",
+	Sms: "sms",
+	Whatsapp: "whatsapp"
+};
+/**
+* Values of PreferenceOrigin known at this SDK version. The wire value is an open
+* string: a value added by a newer server deserializes unchanged, so switch on
+* these with a `default` branch rather than treating the set as closed.
+*/
+const PreferenceOrigin = {
+	ApiKey: "api_key",
+	Import: "import",
+	Keyword: "keyword",
+	PreferencePage: "preference_page",
+	UnsubscribeEvent: "unsubscribe_event",
+	UnsubscribeLink: "unsubscribe_link",
+	User: "user"
+};
+/**
 * Values of SMSErrorCode known at this SDK version. The wire value is an open
 * string: a value added by a newer server deserializes unchanged, so switch on
 * these with a `default` branch rather than treating the set as closed.
@@ -7573,6 +7842,6 @@ const WhatsAppTemplateParameterType = {
 	Video: "video"
 };
 //#endregion
-export { BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, BirdWebhookVerificationError, EmailEventType, EmailLookupFlag, EmailLookupReason, EmailLookupResult, LookupFlag, LookupPropertyStatus, NumberCapability, NumberType, NumbersOrderStatus, SMSErrorCode, SMSKeywordOperation, SMSSuppressionCoverage, SMSSuppressionEndReason, SMSSuppressionOrigin, SMSSuppressionReason, TemplateLanguageStatus, TemplateStatus, VerificationAttemptFailureReason, VerificationChannel, VerificationTerminalReason, WebhookEventType, WhatsAppErrorCode, WhatsAppEventType, WhatsAppTemplateCategory, WhatsAppTemplateParameterType, baseUrlForRegion, regionFromApiKey };
+export { BirdAPIError, BirdAuthError, BirdBadRequestError, BirdBillingError, BirdClient, BirdConflictError, BirdConnectionError, BirdError, BirdInternalError, BirdMisdirectedError, BirdNotFoundError, BirdNotImplementedError, BirdPayloadTooLargeError, BirdPermissionError, BirdPreconditionError, BirdRateLimitError, BirdServiceUnavailableError, BirdTimeoutError, BirdValidationError, BirdWebhookVerificationError, EmailEventType, EmailLookupFlag, EmailLookupReason, EmailLookupResult, LookupFlag, LookupPropertyStatus, NumberCapability, NumberType, NumbersOrderStatus, PreferenceChannel, PreferenceOrigin, SMSErrorCode, SMSKeywordOperation, SMSSuppressionCoverage, SMSSuppressionEndReason, SMSSuppressionOrigin, SMSSuppressionReason, TemplateLanguageStatus, TemplateStatus, VerificationAttemptFailureReason, VerificationChannel, VerificationTerminalReason, WebhookEventType, WhatsAppErrorCode, WhatsAppEventType, WhatsAppTemplateCategory, WhatsAppTemplateParameterType, baseUrlForRegion, regionFromApiKey };
 
 //# sourceMappingURL=index.mjs.map