@zavudev/sdk 0.57.0 → 0.58.0

package/src/resources/phone-numbers.ts

@@ -1,37 +1,31 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+// Generated by zavu-codegen from apps/docs/openapi.json. Do not edit: run `bun run codegen`.
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
-import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
+import { Cursor, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
+import type * as T from '../types';
 
 export class PhoneNumbers extends APIResource {
   /**
+   * Get phone number
+   *
    * Get details of a specific phone number.
    *
-   * @example
-   * ```ts
-   * const phoneNumber = await client.phoneNumbers.retrieve(
-   *   'phoneNumberId',
-   * );
-   * ```
+   * `GET /v1/phone-numbers/{phoneNumberId}`
    */
   retrieve(phoneNumberID: string, options?: RequestOptions): APIPromise<PhoneNumberRetrieveResponse> {
     return this._client.get(path`/v1/phone-numbers/${phoneNumberID}`, options);
   }
 
   /**
+   * Update phone number
+   *
    * Update a phone number's name or sender assignment.
    *
-   * @example
-   * ```ts
-   * const phoneNumber = await client.phoneNumbers.update(
-   *   'phoneNumberId',
-   *   { name: 'Support Line' },
-   * );
-   * ```
+   * `PATCH /v1/phone-numbers/{phoneNumberId}`
    */
   update(
     phoneNumberID: string,
@@ -42,15 +36,11 @@ export class PhoneNumbers extends APIResource {
   }
 
   /**
+   * List phone numbers
+   *
    * List all phone numbers owned by this project.
    *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const ownedPhoneNumber of client.phoneNumbers.list()) {
-   *   // ...
-   * }
-   * ```
+   * `GET /v1/phone-numbers`
    */
   list(
     query: PhoneNumberListParams | null | undefined = {},
@@ -60,20 +50,47 @@ export class PhoneNumbers extends APIResource {
   }
 
   /**
+   * Purchase a phone number
+   *
    * Purchase an available phone number. Requires a paid plan: the Free plan cannot
-   * purchase phone numbers and receives `402` with code `paid_plan_required`. Paid
-   * plans include one US number at no charge. The included number is one per account
-   * and is granted once: claiming it spends the benefit for good, so releasing that
-   * number does not make another one free, and numbers the account already bought do
-   * not consume it.
+   * purchase phone numbers and receives `402` with code `paid_plan_required`.
+   *
+   * **The included number.** A paid plan includes one number at no charge, once per
+   * account: it must be a US or Canadian number (a +1 number) costing $20 a month or
+   * less. `isFreeEligible` in `GET /v1/phone-numbers/available` marks the numbers
+   * that qualify. Claiming it spends the benefit for good, across every team the
+   * account owner owns, so releasing that number does not make another one free.
+   *
+   * **Numbers with regulatory requirements.** Which numbers need regulatory
+   * information is decided per number, not by a fixed country list. The purchase
+   * looks the requirements up for the exact number before charging anything:
+   *
+   * 1. `GET /v1/phone-numbers/requirements?phoneNumber=...`. If `items` is empty,
+   * buy normally.
+   * 2. Create what it asks for: addresses with `POST /v1/addresses`, documents with
+   * `POST /v1/documents`.
+   * 3. Purchase with `type` and `regulatoryRequirements`. The number is bought and
+   * billed at once with `regulatoryStatus: pending_review`.
+   * 4. Poll `GET /v1/phone-numbers/{phoneNumberId}` until `regulatoryStatus` is
+   * `approved`. Assign it to a sender before or after approval; it starts carrying
+   * messages once approved.
+   *
+   * **Reuse.** Information you submitted is kept for your project, per country and
+   * `type`, and a later purchase there may omit `regulatoryRequirements`. Reuse only
+   * happens when what is kept still covers every requirement of the new number and
+   * every address and document in it belongs to the project. Otherwise, or when
+   * nothing is kept, the purchase returns `400 regulatory_compliance_required` with
+   * the missing requirements in `details`.
    *
-   * @example
-   * ```ts
-   * const response = await client.phoneNumbers.purchase({
-   *   phoneNumber: '+15551234567',
-   *   name: 'Primary Line',
-   * });
-   * ```
+   * Invalid values (a missing, unknown or repeated requirement id, an address or
+   * document from another project, or one rejected in review) return `400
+   * invalid_request`. If an address or document cannot be registered for review, the
+   * purchase returns `400 invalid_request` naming the requirement. If the
+   * requirements cannot be looked up, the purchase returns `502
+   * requirements_unavailable`, except for US and Canadian numbers, which are sold as
+   * numbers without requirements. None of these errors charge anything.
+   *
+   * `POST /v1/phone-numbers`
    */
   purchase(
     body: PhoneNumberPurchaseParams,
@@ -83,12 +100,11 @@ export class PhoneNumbers extends APIResource {
   }
 
   /**
+   * Release phone number
+   *
    * Release a phone number. The phone number must not be assigned to a sender.
    *
-   * @example
-   * ```ts
-   * await client.phoneNumbers.release('phoneNumberId');
-   * ```
+   * `DELETE /v1/phone-numbers/{phoneNumberId}`
    */
   release(phoneNumberID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/v1/phone-numbers/${phoneNumberID}`, {
@@ -98,16 +114,24 @@ export class PhoneNumbers extends APIResource {
   }
 
   /**
-   * Get regulatory requirements for purchasing phone numbers in a specific country.
-   * Some countries require additional documentation (addresses, identity documents)
-   * before phone numbers can be activated.
+   * Get regulatory requirements
+   *
+   * Get the regulatory information needed to buy a phone number, for one specific
+   * number or for a country and number type. Prefer `phoneNumber`: the response is
+   * then exactly the list the purchase of that number validates against. Pass each
+   * `requirementTypes[].id` back as `requirementType` in `regulatoryRequirements` on
+   * `POST /v1/phone-numbers`.
+   *
+   * For `phoneNumber`, the requirements of that exact number are returned. When they
+   * cannot be resolved for the number itself, the list for its country and `type` is
+   * returned instead, and the purchase uses the same list. An empty `items` array
+   * means the number needs no regulatory information. If the requirements cannot be
+   * retrieved at all, the response is `502 requirements_unavailable`, never an empty
+   * list.
    *
-   * @example
-   * ```ts
-   * const response = await client.phoneNumbers.requirements({
-   *   countryCode: 'xx',
-   * });
-   * ```
+   * URL-encode the `+` of `phoneNumber` as `%2B`. An unencoded `+` is also accepted.
+   *
+   * `GET /v1/phone-numbers/requirements`
    */
   requirements(
     query: PhoneNumberRequirementsParams,
@@ -117,14 +141,11 @@ export class PhoneNumbers extends APIResource {
   }
 
   /**
+   * Search available phone numbers
+   *
    * Search for available phone numbers to purchase by country and type.
    *
-   * @example
-   * ```ts
-   * const response = await client.phoneNumbers.searchAvailable({
-   *   countryCode: 'xx',
-   * });
-   * ```
+   * `GET /v1/phone-numbers/available`
    */
   searchAvailable(
     query: PhoneNumberSearchAvailableParams,
@@ -134,254 +155,49 @@ export class PhoneNumbers extends APIResource {
   }
 }
 
-export type OwnedPhoneNumbersCursor = Cursor<OwnedPhoneNumber>;
-
-export interface AvailablePhoneNumber {
-  capabilities: PhoneNumberCapabilities;
-
-  phoneNumber: string;
-
-  pricing: PhoneNumberPricing;
-
-  friendlyName?: string;
-
-  locality?: string;
-
-  region?: string;
-}
-
-export interface OwnedPhoneNumber {
-  id: string;
-
-  capabilities: Array<string>;
-
-  createdAt: string;
-
-  phoneNumber: string;
-
-  pricing: OwnedPhoneNumberPricing;
-
-  status: PhoneNumberStatus;
-
-  /**
-   * Optional custom name for the phone number.
-   */
-  name?: string;
-
-  nextRenewalDate?: string;
-
-  /**
-   * Sender ID if the phone number is assigned to a sender.
-   */
-  senderId?: string;
-
-  updatedAt?: string;
-}
-
-export interface OwnedPhoneNumberPricing {
-  /**
-   * Whether this is a free number.
-   */
-  isFreeNumber?: boolean;
-
-  /**
-   * Monthly cost in cents.
-   */
-  monthlyCost?: number;
-
-  /**
-   * Monthly price in USD.
-   */
-  monthlyPrice?: number;
-
-  /**
-   * One-time purchase cost in cents.
-   */
-  upfrontCost?: number;
-}
-
-export interface PhoneNumberCapabilities {
-  mms?: boolean;
-
-  sms?: boolean;
-
-  voice?: boolean;
-}
-
-export interface PhoneNumberPricing {
-  /**
-   * Whether this number qualifies as the plan-included US number on paid plans. The
-   * benefit is one per account: it is never offered again once claimed, not even
-   * after the number is released.
-   */
-  isFreeEligible?: boolean;
-
-  /**
-   * Monthly price in USD.
-   */
-  monthlyPrice?: number;
-
-  /**
-   * One-time purchase price in USD.
-   */
-  upfrontPrice?: number;
-}
-
-export type PhoneNumberStatus = 'active' | 'suspended' | 'pending';
-
-/**
- * Type of phone number. `mobile` is stocked in countries where no geographic
- * (`local`) or non-geographic (`national`) inventory exists, and in several
- * markets it is the only type that can receive SMS.
- */
-export type PhoneNumberType = 'local' | 'national' | 'tollFree' | 'mobile';
+export type OwnedPhoneNumbersCursor = Cursor<T.OwnedPhoneNumber>;
 
-/**
- * A group of requirements for a specific country/phone type combination.
- */
-export interface Requirement {
-  id: string;
+export type AvailablePhoneNumber = T.AvailablePhoneNumber;
 
-  action: string;
+export type OwnedPhoneNumber = T.OwnedPhoneNumber;
 
-  countryCode: string;
+export type OwnedPhoneNumberPricing = T.OwnedPhoneNumberPricing;
 
-  phoneNumberType: string;
+export type PhoneNumberCapabilities = T.PhoneNumberCapabilities;
 
-  requirementTypes: Array<RequirementType>;
-}
+export type PhoneNumberPricing = T.PhoneNumberPricing;
 
-/**
- * Acceptance criteria for a requirement.
- */
-export interface RequirementAcceptanceCriteria {
-  allowedValues?: Array<string> | null;
+export type PhoneNumberStatus = T.PhoneNumberStatus;
 
-  maxLength?: number | null;
+export type PhoneNumberType = T.PhoneNumberType;
 
-  minLength?: number | null;
+export type Requirement = T.Requirement;
 
-  regexPattern?: string | null;
-}
+export type RequirementAcceptanceCriteria = T.RequirementAcceptanceCriteria;
 
-/**
- * Type of requirement field.
- */
-export type RequirementFieldType = 'textual' | 'address' | 'document' | 'action';
+export type RequirementFieldType = T.RequirementFieldType;
 
-/**
- * A specific requirement type within a requirement group.
- */
-export interface RequirementType {
-  id: string;
-
-  description: string;
-
-  name: string;
-
-  /**
-   * Type of requirement field.
-   */
-  type: RequirementFieldType;
-
-  /**
-   * Acceptance criteria for a requirement.
-   */
-  acceptanceCriteria?: RequirementAcceptanceCriteria;
+export type RequirementType = T.RequirementType;
 
-  example?: string | null;
-}
+export type PhoneNumberRetrieveResponse = T.PhoneNumberResponse;
 
-export interface PhoneNumberRetrieveResponse {
-  phoneNumber: OwnedPhoneNumber;
-}
+export type PhoneNumberUpdateResponse = T.PhoneNumberResponse;
 
-export interface PhoneNumberUpdateResponse {
-  phoneNumber: OwnedPhoneNumber;
-}
+export type PhoneNumberPurchaseResponse = T.PhoneNumberResponse;
 
-export interface PhoneNumberPurchaseResponse {
-  phoneNumber: OwnedPhoneNumber;
-}
+export type PhoneNumberRequirementsResponse = T.GetPhoneNumberRequirementsResponse;
 
-export interface PhoneNumberRequirementsResponse {
-  items: Array<Requirement>;
-}
+export type PhoneNumberSearchAvailableResponse = T.SearchAvailablePhoneNumbersResponse;
 
-export interface PhoneNumberSearchAvailableResponse {
-  items: Array<AvailablePhoneNumber>;
-}
+export type PhoneNumberUpdateParams = T.PhoneNumbersUpdateParams;
 
-export interface PhoneNumberUpdateParams {
-  /**
-   * Custom name for the phone number. Set to null to clear.
-   */
-  name?: string | null;
+export type PhoneNumberListParams = T.PhoneNumbersListParams;
 
-  /**
-   * Sender ID to assign the phone number to. Set to null to unassign.
-   */
-  senderId?: string | null;
-}
+export type PhoneNumberPurchaseParams = T.PhoneNumbersPurchaseParams;
 
-export interface PhoneNumberListParams extends CursorParams {
-  /**
-   * Filter by phone number status.
-   */
-  status?: PhoneNumberStatus;
-}
+export type PhoneNumberRequirementsParams = T.PhoneNumbersRequirementsParams;
 
-export interface PhoneNumberPurchaseParams {
-  /**
-   * Phone number in E.164 format.
-   */
-  phoneNumber: string;
-
-  /**
-   * Optional custom name for the phone number.
-   */
-  name?: string;
-}
-
-export interface PhoneNumberRequirementsParams {
-  /**
-   * Two-letter ISO country code.
-   */
-  countryCode: string;
-
-  /**
-   * Type of phone number (local, mobile, tollFree).
-   */
-  type?: PhoneNumberType;
-}
-
-export interface PhoneNumberSearchAvailableParams {
-  /**
-   * Two-letter ISO country code.
-   */
-  countryCode: string;
-
-  /**
-   * Comma-separated capabilities the number must have: `sms`, `voice`, `mms`.
-   * Numbers missing any of them are dropped.
-   */
-  capabilities?: string;
-
-  /**
-   * Search for numbers containing this string.
-   */
-  contains?: string;
-
-  /**
-   * Maximum number of results to return.
-   */
-  limit?: number;
-
-  /**
-   * Type of phone number to search for.
-   */
-  type?: PhoneNumberType;
-}
+export type PhoneNumberSearchAvailableParams = T.PhoneNumbersSearchAvailableParams;
 
 export declare namespace PhoneNumbers {
   export {

package/src/resources/regulatory-documents.ts

@@ -1,28 +1,21 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+// Generated by zavu-codegen from apps/docs/openapi.json. Do not edit: run `bun run codegen`.
 
 import { APIResource } from '../core/resource';
 import { APIPromise } from '../core/api-promise';
-import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
+import { Cursor, PagePromise } from '../core/pagination';
 import { buildHeaders } from '../internal/headers';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
+import type * as T from '../types';
 
 export class RegulatoryDocuments extends APIResource {
   /**
+   * Create document
+   *
    * Create a regulatory document record after uploading the file. Use the upload-url
    * endpoint first to get an upload URL.
    *
-   * @example
-   * ```ts
-   * const regulatoryDocument =
-   *   await client.regulatoryDocuments.create({
-   *     documentType: 'passport',
-   *     fileSize: 102400,
-   *     mimeType: 'image/jpeg',
-   *     name: 'Passport Scan',
-   *     storageId: 'kg2abc123...',
-   *   });
-   * ```
+   * `POST /v1/documents`
    */
   create(
     body: RegulatoryDocumentCreateParams,
@@ -32,28 +25,22 @@ export class RegulatoryDocuments extends APIResource {
   }
 
   /**
+   * Get document
+   *
    * Get a specific regulatory document.
    *
-   * @example
-   * ```ts
-   * const regulatoryDocument =
-   *   await client.regulatoryDocuments.retrieve('documentId');
-   * ```
+   * `GET /v1/documents/{documentId}`
    */
   retrieve(documentID: string, options?: RequestOptions): APIPromise<RegulatoryDocumentRetrieveResponse> {
     return this._client.get(path`/v1/documents/${documentID}`, options);
   }
 
   /**
+   * List documents
+   *
    * List regulatory documents for this project.
    *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const regulatoryDocument of client.regulatoryDocuments.list()) {
-   *   // ...
-   * }
-   * ```
+   * `GET /v1/documents`
    */
   list(
     query: RegulatoryDocumentListParams | null | undefined = {},
@@ -63,12 +50,11 @@ export class RegulatoryDocuments extends APIResource {
   }
 
   /**
+   * Delete document
+   *
    * Delete a regulatory document. Cannot delete verified documents.
    *
-   * @example
-   * ```ts
-   * await client.regulatoryDocuments.delete('documentId');
-   * ```
+   * `DELETE /v1/documents/{documentId}`
    */
   delete(documentID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/v1/documents/${documentID}`, {
@@ -78,98 +64,31 @@ export class RegulatoryDocuments extends APIResource {
   }
 
   /**
+   * Get document upload URL
+   *
    * Get a presigned URL to upload a document file. After uploading, use the
    * storageId to create the document record.
    *
-   * @example
-   * ```ts
-   * const response =
-   *   await client.regulatoryDocuments.uploadURL();
-   * ```
+   * `POST /v1/documents/upload-url`
    */
   uploadURL(options?: RequestOptions): APIPromise<RegulatoryDocumentUploadURLResponse> {
     return this._client.post('/v1/documents/upload-url', options);
   }
 }
 
-export type RegulatoryDocumentsCursor = Cursor<RegulatoryDocument>;
-
-/**
- * A regulatory document for phone number requirements.
- */
-export interface RegulatoryDocument {
-  id: string;
-
-  createdAt: string;
-
-  documentType:
-    | 'passport'
-    | 'national_id'
-    | 'drivers_license'
-    | 'utility_bill'
-    | 'tax_id'
-    | 'business_registration'
-    | 'proof_of_address'
-    | 'other';
-
-  name: string;
-
-  status: 'pending' | 'uploaded' | 'verified' | 'rejected';
-
-  fileSize?: number;
-
-  mimeType?: string;
-
-  rejectionReason?: string | null;
-
-  updatedAt?: string;
-}
-
-export interface RegulatoryDocumentCreateResponse {
-  /**
-   * A regulatory document for phone number requirements.
-   */
-  document: RegulatoryDocument;
-}
+export type RegulatoryDocumentsCursor = Cursor<T.RegulatoryDocument>;
 
-export interface RegulatoryDocumentRetrieveResponse {
-  /**
-   * A regulatory document for phone number requirements.
-   */
-  document: RegulatoryDocument;
-}
+export type RegulatoryDocument = T.RegulatoryDocument;
 
-export interface RegulatoryDocumentUploadURLResponse {
-  /**
-   * Pre-signed URL for uploading the file.
-   */
-  uploadUrl: string;
-}
-
-export interface RegulatoryDocumentCreateParams {
-  documentType:
-    | 'passport'
-    | 'national_id'
-    | 'drivers_license'
-    | 'utility_bill'
-    | 'tax_id'
-    | 'business_registration'
-    | 'proof_of_address'
-    | 'other';
-
-  fileSize: number;
+export type RegulatoryDocumentCreateResponse = T.RegulatoryDocumentResponse;
 
-  mimeType: string;
+export type RegulatoryDocumentRetrieveResponse = T.RegulatoryDocumentResponse;
 
-  name: string;
+export type RegulatoryDocumentUploadURLResponse = T.UploadUrlResponse;
 
-  /**
-   * Storage ID from the upload-url endpoint.
-   */
-  storageId: string;
-}
+export type RegulatoryDocumentCreateParams = T.RegulatoryDocumentsCreateParams;
 
-export interface RegulatoryDocumentListParams extends CursorParams {}
+export type RegulatoryDocumentListParams = T.RegulatoryDocumentsListParams;
 
 export declare namespace RegulatoryDocuments {
   export {