celitech-sdk 1.3.61 → 1.3.63

package/dist/index.js

@@ -45,8 +45,14 @@ module.exports = __toCommonJS(src_exports);
 // src/http/handlers/handler-chain.ts
 var RequestHandlerChain = class {
   constructor() {
+    /** Array of handlers in the chain */
     this.handlers = [];
   }
+  /**
+   * Adds a handler to the end of the chain.
+   * Links the new handler to the previous one in the chain.
+   * @param handler - The request handler to add
+   */
   addHandler(handler) {
     if (this.handlers.length > 0) {
       const previousHandler = this.handlers[this.handlers.length - 1];
@@ -54,12 +60,26 @@ var RequestHandlerChain = class {
     }
     this.handlers.push(handler);
   }
+  /**
+   * Executes the handler chain for a standard request.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the HTTP response
+   * @throws Error if no handlers are added to the chain
+   */
   async callChain(request) {
     if (!this.handlers.length) {
       throw new Error("No handlers added to the chain");
     }
     return this.handlers[0].handle(request);
   }
+  /**
+   * Executes the handler chain for a streaming request.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to process
+   * @returns An async generator that yields HTTP responses
+   * @throws Error if no handlers are added to the chain
+   */
   async *streamChain(request) {
     if (!this.handlers.length) {
       throw new Error("No handlers added to the chain");
@@ -70,6 +90,12 @@ var RequestHandlerChain = class {
 
 // src/http/error.ts
 var HttpError = class extends Error {
+  /**
+   * Creates a new HTTP error.
+   * @param metadata - HTTP response metadata
+   * @param raw - Raw response object (optional)
+   * @param error - Custom error message (optional, defaults to status text)
+   */
   constructor(metadata, raw, error) {
     super(error);
     this.error = metadata.statusText;
@@ -80,12 +106,35 @@ var HttpError = class extends Error {
 
 // src/http/hooks/custom-hook.ts
 var CustomHook = class {
+  /**
+   * Called before an HTTP request is sent.
+   * Default implementation returns the request unchanged.
+   * @param request - The HTTP request to be sent
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to the unmodified request
+   */
   async beforeRequest(request, params) {
     return request;
   }
+  /**
+   * Called after a successful HTTP response is received.
+   * Default implementation returns the response unchanged.
+   * @param request - The original HTTP request
+   * @param response - The HTTP response received
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to the unmodified response
+   */
   async afterResponse(request, response, params) {
     return response;
   }
+  /**
+   * Called when an HTTP request results in an error.
+   * Default implementation wraps the error response in an HttpError object.
+   * @param request - The original HTTP request
+   * @param response - The error response received
+   * @param params - Additional custom parameters
+   * @returns A promise that resolves to an HttpError object
+   */
   async onError(request, response, params) {
     return new HttpError(response.metadata, response.raw);
   }
@@ -93,6 +142,11 @@ var CustomHook = class {
 
 // src/http/serialization/base-serializer.ts
 var Serializer = class {
+  /**
+   * Serializes a parameter value based on its type and serialization style.
+   * @param param - The request parameter to serialize
+   * @returns The serialized string representation
+   */
   serializeValue(param) {
     if (Array.isArray(param.value)) {
       return this.serializeArray(param.value, param);
@@ -102,6 +156,11 @@ var Serializer = class {
     }
     return this.serializePrimitive(param);
   }
+  /**
+   * Serializes a primitive value (string, number, boolean).
+   * @param param - The request parameter containing the primitive value
+   * @returns The serialized primitive string
+   */
   serializePrimitive(param) {
     if (param.style === "label" /* LABEL */) {
       return `.${param.value}`;
@@ -112,6 +171,12 @@ var Serializer = class {
     }
     return `${param.value}`;
   }
+  /**
+   * Serializes an array value according to the specified style.
+   * @param value - The array to serialize
+   * @param param - The request parameter configuration
+   * @returns The serialized array string
+   */
   serializeArray(value, param) {
     if (param.explode) {
       this.serializeArrayExploded(value, param);
@@ -132,6 +197,12 @@ var Serializer = class {
     }
     return `${value.join(",")}`;
   }
+  /**
+   * Serializes an array in exploded format where each value is a separate parameter.
+   * @param value - The array to serialize
+   * @param param - The request parameter configuration
+   * @returns The serialized exploded array string
+   */
   serializeArrayExploded(value, param) {
     if (param.style === "simple" /* SIMPLE */) {
       return value.map((val) => `${val}`).join(",");
@@ -144,6 +215,12 @@ var Serializer = class {
     }
     return `${value.join(",")}`;
   }
+  /**
+   * Serializes an object value according to the specified style.
+   * @param obj - The object to serialize
+   * @param param - The request parameter configuration
+   * @returns The serialized object string
+   */
   serializeObject(obj, param) {
     if (param.explode) {
       if (param.style === "simple" /* SIMPLE */) {
@@ -171,6 +248,11 @@ var Serializer = class {
     }
     return Object.entries(obj).map(([key, val]) => `${key}=${val}`).join("&");
   }
+  /**
+   * Type guard to check if a value is a non-null object.
+   * @param value - The value to check
+   * @returns True if the value is an object and not null
+   */
   isNonNullObject(value) {
     return typeof value === "object" && value !== null;
   }
@@ -181,6 +263,14 @@ var TransportHookAdapter = class {
   constructor() {
     this.hook = new CustomHook();
   }
+  /**
+   * Invokes the custom hook before sending the request.
+   * Converts the Request to HttpRequest format, calls the hook, then converts back.
+   *
+   * @param request - The internal Request object
+   * @param params - Additional parameters to pass to the hook
+   * @returns The modified Request after hook processing
+   */
   async beforeRequest(request, params) {
     const hookRequest = this.requestToHookRequest(request);
     const newRequest = await this.hook.beforeRequest(hookRequest, params);
@@ -195,14 +285,39 @@ var TransportHookAdapter = class {
     });
     return newTransportRequest;
   }
+  /**
+   * Invokes the custom hook after receiving a response.
+   * Converts the Request to HttpRequest format and calls the hook with the response.
+   *
+   * @param request - The internal Request object
+   * @param response - The HTTP response received
+   * @param params - Additional parameters to pass to the hook
+   * @returns The potentially modified response after hook processing
+   */
   async afterResponse(request, response, params) {
     const hookRequest = this.requestToHookRequest(request);
     return this.hook.afterResponse(hookRequest, response, params);
   }
+  /**
+   * Invokes the custom hook when an error occurs.
+   * Converts the Request to HttpRequest format and calls the error hook.
+   *
+   * @param request - The internal Request object
+   * @param response - The HTTP response that triggered the error
+   * @param params - Additional parameters to pass to the hook
+   * @returns The HttpError from the hook
+   */
   async onError(request, response, params) {
     const hookRequest = this.requestToHookRequest(request);
     return this.hook.onError(hookRequest, response, params);
   }
+  /**
+   * Converts the internal Request representation to the hook's HttpRequest format.
+   * Extracts parameter values from RequestParameter wrappers.
+   *
+   * @param request - The internal Request object
+   * @returns An HttpRequest object for hook processing
+   */
   requestToHookRequest(request) {
     const hookHeaders = /* @__PURE__ */ new Map();
     request.headers.forEach((header, key) => {
@@ -227,6 +342,16 @@ var TransportHookAdapter = class {
     };
     return hookRequest;
   }
+  /**
+   * Converts hook parameter maps back to RequestParameter format.
+   * Preserves serialization metadata from the original parameters.
+   *
+   * @template T - The parameter value type
+   * @param hookParams - The parameter map from hook processing
+   * @param originalTransportParams - The original RequestParameter map for metadata
+   * @param encode - Whether to encode the parameters
+   * @returns A map of RequestParameter objects for transport
+   */
   hookParamsToTransportParams(hookParams, originalTransportParams, encode) {
     const transportParams = /* @__PURE__ */ new Map();
     hookParams.forEach((hookParamValue, hookParamKey) => {
@@ -288,6 +413,14 @@ var HookHandler = class {
   constructor(hook) {
     this.hook = hook;
   }
+  /**
+   * Handles a standard HTTP request with hook invocation.
+   * Calls beforeRequest hook, processes the request, and calls afterResponse or onError hooks.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the HTTP response
+   * @throws Error if no next handler is set, or if error handling fails
+   */
   async handle(request) {
     var _a;
     if (!this.next) {
@@ -321,6 +454,14 @@ StatusCode: ${response.metadata.status}
 Body: ${decodedBody}`
     );
   }
+  /**
+   * Handles a streaming HTTP request with hook invocation.
+   * Calls beforeRequest hook and afterResponse/onError hooks for each chunk.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to process
+   * @returns An async generator that yields HTTP responses
+   * @throws Error if no next handler is set, or if error handling fails
+   */
   async *stream(request) {
     if (!this.next) {
       throw new Error("No next handler set in hook handler.");
@@ -337,6 +478,12 @@ Body: ${decodedBody}`
       }
     }
   }
+  /**
+   * Extracts hook parameters from the request configuration.
+   * @template T - The response data type
+   * @param request - The HTTP request
+   * @returns A map of hook parameter names to values
+   */
   getHookParams(_request) {
     const hookParams = /* @__PURE__ */ new Map();
     return hookParams;
@@ -348,9 +495,19 @@ var import_zod = require("zod");
 
 // src/http/utils/response-matcher.ts
 var ResponseMatcher = class {
+  /**
+   * Creates a new response matcher.
+   * @param responses - Array of possible response definitions for an endpoint
+   */
   constructor(responses) {
     this.responses = responses;
   }
+  /**
+   * Finds the matching response definition for an HTTP response.
+   * Matches based on status code and content type from the response headers.
+   * @param response - The HTTP response to match
+   * @returns The matching response definition, or undefined if no match found
+   */
   getResponseDefinition(response) {
     var _a;
     const rawContentType = ((_a = response.metadata.headers["content-type"]) == null ? void 0 : _a.toLocaleLowerCase()) || "";
@@ -370,10 +527,23 @@ var ResponseMatcher = class {
 
 // src/http/handlers/response-validation-handler.ts
 var ResponseValidationHandler = class {
+  /**
+   * Handles a standard HTTP request and validates its response.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the validated HTTP response
+   */
   async handle(request) {
     const response = await this.next.handle(request);
     return this.decodeBody(request, response);
   }
+  /**
+   * Handles a streaming HTTP request and validates response chunks.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to process
+   * @returns An async generator that yields validated HTTP responses
+   * @throws Error if response headers are enabled (streaming not supported with headers)
+   */
   async *stream(request) {
     const stream = this.next.stream(request);
     for await (const response of stream) {
@@ -467,6 +637,14 @@ var ResponseValidationHandler = class {
       data: this.validate(request, responseDefinition, json)
     };
   }
+  /**
+   * Validates response data against the expected schema if validation is enabled.
+   * @template T - The expected data type
+   * @param request - The HTTP request containing validation settings
+   * @param response - The response definition with schema
+   * @param data - The data to validate
+   * @returns The validated data (parsed if validation enabled, raw otherwise)
+   */
   validate(request, response, data) {
     var _a;
     if ((_a = request.validation) == null ? void 0 : _a.responseValidation) {
@@ -474,9 +652,21 @@ var ResponseValidationHandler = class {
     }
     return data;
   }
+  /**
+   * Checks if a response should contain data based on its schema and status.
+   * @template T - The response data type
+   * @param responseDefinition - The response definition
+   * @param response - The HTTP response
+   * @returns True if the response should have content, false otherwise
+   */
   hasContent(responseDefinition, response) {
     return !!responseDefinition.schema && !(responseDefinition.schema instanceof import_zod.ZodUndefined) && response.metadata.status !== 204;
   }
+  /**
+   * Parses URL-encoded data into an object.
+   * @param urlEncodedData - The URL-encoded string
+   * @returns An object with decoded key-value pairs
+   */
   fromUrlEncoded(urlEncodedData) {
     const pairs = urlEncodedData.split("&");
     const result = {};
@@ -488,6 +678,11 @@ var ResponseValidationHandler = class {
     });
     return result;
   }
+  /**
+   * Parses multipart form data into an object.
+   * @param arrayBuffer - The raw form data as ArrayBuffer
+   * @returns An object with form field names and values
+   */
   fromFormData(arrayBuffer) {
     const decoder = new TextDecoder();
     const text = decoder.decode(arrayBuffer);
@@ -511,6 +706,11 @@ var import_zod2 = require("zod");
 
 // src/http/errors/validation-error.ts
 var ValidationError = class extends Error {
+  /**
+   * Creates a new validation error from a Zod error.
+   * @param zodError - The Zod validation error containing issue details
+   * @param object - The object that failed validation
+   */
   constructor(zodError, object) {
     let actual;
     try {
@@ -531,6 +731,13 @@ var ValidationError = class extends Error {
 
 // src/http/handlers/request-validation-handler.ts
 var RequestValidationHandler = class {
+  /**
+   * Handles a standard HTTP request with validation.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to validate
+   * @returns A promise that resolves to the HTTP response
+   * @throws Error if no next handler is set
+   */
   async handle(request) {
     if (!this.next) {
       throw new Error("No next handler set in ContentTypeHandler.");
@@ -538,6 +745,13 @@ var RequestValidationHandler = class {
     this.validateRequest(request);
     return this.next.handle(request);
   }
+  /**
+   * Handles a streaming HTTP request with validation.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to validate
+   * @returns An async generator that yields HTTP responses
+   * @throws Error if no next handler is set
+   */
   async *stream(request) {
     if (!this.next) {
       throw new Error("No next handler set in ContentTypeHandler.");
@@ -545,6 +759,11 @@ var RequestValidationHandler = class {
     this.validateRequest(request);
     yield* this.next.stream(request);
   }
+  /**
+   * Validates and serializes the request body based on its content type.
+   * @param request - The HTTP request to validate
+   * @throws ValidationError if Zod schema validation fails
+   */
   validateRequest(request) {
     var _a, _b;
     if (request.requestContentType === "json" /* Json */) {
@@ -567,6 +786,11 @@ var RequestValidationHandler = class {
       request.body = JSON.stringify((_b = request.requestSchema) == null ? void 0 : _b.parse(request.body));
     }
   }
+  /**
+   * Converts request body to URL-encoded form data format.
+   * @param request - The HTTP request with body to convert
+   * @returns URL-encoded string representation of the body
+   */
   toFormUrlEncoded(request) {
     var _a;
     if (request.body === void 0) {
@@ -599,6 +823,14 @@ var RequestValidationHandler = class {
     }
     return "";
   }
+  /**
+   * Converts request body to multipart form data format.
+   * Handles files (ArrayBuffer), arrays, and regular values.
+   * @param body - The request body object
+   * @param filename - Optional filename for single file uploads
+   * @param filenames - Optional filenames array for array of file uploads
+   * @returns FormData object with serialized body
+   */
   toFormData(body, filename, filenames) {
     const formData = new FormData();
     Object.keys(body).forEach((key) => {
@@ -633,6 +865,9 @@ var LineDecoder = class {
   /**
    * Splits the given chunk into lines.
    * Stores incomplete lines in a buffer and returns them when the next chunk arrives.
+   *
+   * @param chunk - The data chunk to split into lines
+   * @returns An array of complete lines as Uint8Array
    */
   splitLines(chunk) {
     this.lineBuffer += this.decoder.decode(chunk);
@@ -647,7 +882,12 @@ var LineDecoder = class {
     }
     return lines;
   }
-  /** Returns the remaining lines in the buffer. */
+  /**
+   * Returns the remaining lines in the buffer.
+   * Call this after the stream ends to get any incomplete final line.
+   *
+   * @returns An array containing the buffered line, or empty if buffer is empty
+   */
   flush() {
     if (this.lineBuffer.length === 0) {
       return [];
@@ -665,9 +905,16 @@ var RequestFetchAdapter = class {
     this.requestInit = {};
     this.setMethod(request.method);
     this.setHeaders(request.getHeaders());
+    this.setCookies(request.getCookies());
     this.setBody(request.body);
     this.setTimeout(request.config.timeoutMs);
   }
+  /**
+   * Executes the HTTP request and returns the response.
+   * Fetches the full response body as an ArrayBuffer.
+   *
+   * @returns A promise resolving to the HTTP response with metadata and body
+   */
   async send() {
     const response = await fetch(this.request.constructFullUrl(), this.requestInit);
     const metadata = {
@@ -680,6 +927,13 @@ var RequestFetchAdapter = class {
       raw: await response.clone().arrayBuffer()
     };
   }
+  /**
+   * Executes the HTTP request as a stream, yielding chunks as they arrive.
+   * Uses the Fetch API's ReadableStream and LineDecoder to split into lines.
+   *
+   * @returns An async generator yielding HTTP response chunks
+   * @throws Error if responseHeaders is enabled (streaming not supported with responseHeaders)
+   */
   async *stream() {
     const response = await fetch(this.request.constructFullUrl(), this.requestInit);
     const metadata = {
@@ -744,6 +998,19 @@ var RequestFetchAdapter = class {
       headers
     };
   }
+  setCookies(cookies) {
+    if (!cookies || Object.keys(cookies).length === 0) {
+      return;
+    }
+    const cookieString = Object.entries(cookies).map(([key, value]) => `${key}=${value}`).join("; ");
+    this.requestInit = {
+      ...this.requestInit,
+      headers: {
+        ...this.requestInit.headers,
+        Cookie: cookieString
+      }
+    };
+  }
   setTimeout(timeoutMs) {
     if (!timeoutMs) {
       return;
@@ -767,9 +1034,21 @@ var RequestFetchAdapter = class {
 
 // src/http/handlers/terminating-handler.ts
 var TerminatingHandler = class {
+  /**
+   * Executes the actual HTTP request using the configured client adapter.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to execute
+   * @returns A promise that resolves to the HTTP response
+   */
   async handle(request) {
     return new RequestFetchAdapter(request).send();
   }
+  /**
+   * Executes a streaming HTTP request using the configured client adapter.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to execute
+   * @returns An async generator that yields HTTP responses
+   */
   async *stream(request) {
     yield* new RequestFetchAdapter(request).stream();
   }
@@ -777,6 +1056,14 @@ var TerminatingHandler = class {
 
 // src/http/handlers/retry-handler.ts
 var RetryHandler = class {
+  /**
+   * Handles a standard HTTP request with retry logic.
+   * Retries failed requests based on the configured retry settings.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the HTTP response
+   * @throws Error if no next handler is set, or if all retry attempts fail
+   */
   async handle(request) {
     if (!this.next) {
       throw new Error("No next handler set in retry handler.");
@@ -793,6 +1080,13 @@ var RetryHandler = class {
     }
     throw new Error("Error retrying request.");
   }
+  /**
+   * Handles a streaming HTTP request with retry logic.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to process
+   * @returns An async generator that yields HTTP responses
+   * @throws Error if no next handler is set, or if all retry attempts fail
+   */
   async *stream(request) {
     if (!this.next) {
       throw new Error("No next handler set in retry handler.");
@@ -810,9 +1104,20 @@ var RetryHandler = class {
     }
     throw new Error("Error retrying request.");
   }
+  /**
+   * Determines if an error should trigger a retry.
+   * Retries server errors (5xx), request timeouts (408), and rate limits (429).
+   * @param error - The error to check
+   * @returns True if the request should be retried, false otherwise
+   */
   shouldRetry(error) {
     return error instanceof HttpError && (error.metadata.status >= 500 || error.metadata.status === 408 || error.metadata.status === 429);
   }
+  /**
+   * Delays execution for a specified duration before retrying.
+   * @param delayMs - The delay in milliseconds (optional)
+   * @returns A promise that resolves after the delay
+   */
   delay(delayMs) {
     if (!delayMs) {
       return Promise.resolve();
@@ -830,6 +1135,14 @@ function isRequestCursorPagination(pagination) {
 
 // src/http/handlers/oauth-handler.ts
 var OAuthHandler = class {
+  /**
+   * Handles a standard HTTP request with OAuth authentication.
+   * Manages access tokens and adds Authorization headers.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to process
+   * @returns A promise that resolves to the HTTP response
+   * @throws Error if no next handler is set
+   */
   async handle(request) {
     if (!this.next) {
       throw new Error(`No next handler set in OAuthHandler`);
@@ -844,6 +1157,13 @@ var OAuthHandler = class {
     await this.manageToken(request);
     return this.next.handle(request);
   }
+  /**
+   * Handles a streaming HTTP request with OAuth authentication.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to process
+   * @returns An async generator that yields HTTP responses
+   * @throws Error if no next handler is set
+   */
   async *stream(request) {
     if (!this.next) {
       throw new Error(`No next handler set in OAuthHandler`);
@@ -851,6 +1171,10 @@ var OAuthHandler = class {
     await this.manageToken(request);
     yield* this.next.stream(request);
   }
+  /**
+   * Retrieves an access token for the required scopes and adds it to the request.
+   * @param request - The HTTP request to add the token to
+   */
   async manageToken(request) {
     if (!request.scopes) {
       return;
@@ -860,6 +1184,11 @@ var OAuthHandler = class {
       this.addAccessTokenHeader(request, token.accessToken);
     }
   }
+  /**
+   * Adds the OAuth access token to the request's Authorization header.
+   * @param request - The HTTP request to modify
+   * @param token - The access token to add
+   */
   addAccessTokenHeader(request, token) {
     request.addHeaderParam("Authorization", {
       key: "Authorization",
@@ -876,8 +1205,14 @@ var OAuthHandler = class {
 
 // src/http/client.ts
 var HttpClient = class {
+  /**
+   * Creates a new HTTP client with configured request handlers.
+   * @param config - SDK configuration including base URL and authentication
+   * @param hook - Optional custom hook for request/response interception
+   */
   constructor(config, hook = new CustomHook()) {
     this.config = config;
+    /** Chain of request handlers that process requests in sequence */
     this.requestHandlerChain = new RequestHandlerChain();
     this.requestHandlerChain.addHandler(new ResponseValidationHandler());
     this.requestHandlerChain.addHandler(new RequestValidationHandler());
@@ -886,12 +1221,32 @@ var HttpClient = class {
     this.requestHandlerChain.addHandler(new HookHandler(hook));
     this.requestHandlerChain.addHandler(new TerminatingHandler());
   }
+  /**
+   * Executes a standard HTTP request.
+   * @template T - The expected response data type
+   * @param request - The HTTP request to execute
+   * @returns A promise that resolves to the HTTP response
+   */
   call(request) {
     return this.requestHandlerChain.callChain(request);
   }
+  /**
+   * Executes a streaming HTTP request that yields responses incrementally.
+   * @template T - The expected response data type for each chunk
+   * @param request - The HTTP request to execute
+   * @returns An async generator that yields HTTP responses
+   */
   async *stream(request) {
     yield* this.requestHandlerChain.streamChain(request);
   }
+  /**
+   * Executes a paginated HTTP request and extracts the page data from the response.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The paginated HTTP request to execute
+   * @returns A promise that resolves to the paginated HTTP response
+   * @throws Error if the response contains no data to paginate through
+   */
   async callPaginated(request) {
     const response = await this.call(request);
     if (!response.data) {
@@ -903,6 +1258,14 @@ var HttpClient = class {
       data: page
     };
   }
+  /**
+   * Executes a cursor-paginated HTTP request and extracts both page data and the next cursor.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The cursor-paginated HTTP request to execute
+   * @returns A promise that resolves to the cursor-paginated HTTP response with next cursor
+   * @throws Error if the response contains no data to paginate through
+   */
   async callCursorPaginated(request) {
     const response = await this.call(request);
     if (!response.data) {
@@ -916,12 +1279,29 @@ var HttpClient = class {
       nextCursor
     };
   }
+  /**
+   * Updates the base URL for all subsequent requests.
+   * @param url - The new base URL to use
+   */
   setBaseUrl(url) {
     this.config.baseUrl = url;
   }
+  /**
+   * Updates the SDK configuration.
+   * @param config - The new SDK configuration
+   */
   setConfig(config) {
     this.config = config;
   }
+  /**
+   * Extracts page data from a full API response using the configured pagination path.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The request containing pagination configuration
+   * @param data - The full response data to extract the page from
+   * @returns The extracted and parsed page data
+   * @throws Error if pagination is not configured or page extraction fails
+   */
   getPage(request, data) {
     var _a;
     if (!request.pagination) {
@@ -939,6 +1319,14 @@ var HttpClient = class {
     }
     return page;
   }
+  /**
+   * Extracts the next cursor from a full API response for cursor-based pagination.
+   * @template FullResponse - The complete response type from the API
+   * @template Page - The type of a single page of data
+   * @param request - The request containing cursor pagination configuration
+   * @param data - The full response data to extract the cursor from
+   * @returns The next cursor string, null if no more pages, or undefined if not cursor pagination
+   */
   getNextCursor(request, data) {
     var _a, _b;
     if (!isRequestCursorPagination(request.pagination)) {
@@ -990,6 +1378,14 @@ var import_zod3 = __toESM(require("zod"));
 
 // src/http/serialization/path-serializer.ts
 var PathSerializer = class extends Serializer {
+  /**
+   * Serializes path parameters into a URL path by replacing template placeholders.
+   * @param pathPattern - The URL path pattern with {placeholders}
+   * @param pathArguments - Map of parameter names to their values
+   * @returns The path with placeholders replaced by serialized values
+   * @example
+   * serialize("/users/{id}", Map([["id", {key: "id", value: 123}]])) returns "/users/123"
+   */
   serialize(pathPattern, pathArguments) {
     let serializedPath = pathPattern;
     pathArguments.forEach((param) => {
@@ -1001,6 +1397,13 @@ var PathSerializer = class extends Serializer {
 
 // src/http/serialization/query-serializer.ts
 var QuerySerializer = class extends Serializer {
+  /**
+   * Serializes query parameters into a URL query string.
+   * @param queryParams - Map of query parameter names to their values
+   * @returns A query string starting with "?" if parameters exist, empty string otherwise
+   * @example
+   * serialize(Map([["name", {...}], ["age", {...}]])) returns "?name=John&age=30"
+   */
   serialize(queryParams) {
     if (!queryParams || !queryParams.size) {
       return "";
@@ -1018,6 +1421,11 @@ var QuerySerializer = class extends Serializer {
 
 // src/http/serialization/header-serializer.ts
 var HeaderSerializer = class extends Serializer {
+  /**
+   * Serializes header parameters into a headers object.
+   * @param headerParams - Map of header names to their parameter values
+   * @returns A HeadersInit object with serialized header values, or undefined if no headers
+   */
   serialize(headerParams) {
     if (!headerParams || !headerParams.size) {
       return void 0;
@@ -1033,6 +1441,83 @@ var HeaderSerializer = class extends Serializer {
   }
 };
 
+// src/http/serialization/cookie-serializer.ts
+var CookieSerializer = class {
+  /**
+   * Serializes cookie parameters into a cookie object.
+   * @param cookieParams - Map of cookie names to their parameter values
+   * @returns A record of cookie names to serialized values, or undefined if no cookies
+   */
+  serialize(cookieParams) {
+    if (!cookieParams || !cookieParams.size) {
+      return void 0;
+    }
+    const cookies = {};
+    cookieParams.forEach((param) => {
+      if (!param.key || param.value === void 0) {
+        return;
+      }
+      cookies[param.key] = this.serializeCookieValue(param);
+    });
+    return cookies;
+  }
+  /**
+   * Serializes a single cookie value based on its type.
+   * @param param - The cookie parameter to serialize
+   * @returns The serialized cookie value string
+   */
+  serializeCookieValue(param) {
+    if (Array.isArray(param.value)) {
+      return this.serializeArray(param.value, param);
+    }
+    if (this.isNonNullObject(param.value)) {
+      return this.serializeObject(param.value, param);
+    }
+    return this.serializePrimitive(param.value);
+  }
+  /**
+   * Serializes a primitive cookie value.
+   * @param value - The primitive value to serialize
+   * @returns The string representation of the value
+   */
+  serializePrimitive(value) {
+    return `${value}`;
+  }
+  /**
+   * Serializes an array cookie value.
+   * @param value - The array to serialize
+   * @param param - The cookie parameter configuration
+   * @returns The serialized array string
+   */
+  serializeArray(value, param) {
+    if (param.explode) {
+      if (value.length === 0)
+        return "";
+      const first = value[0];
+      const rest = value.slice(1).map((v) => `${param.key}=${v}`).join("; ");
+      return rest ? `${first}; ${rest}` : `${first}`;
+    }
+    return value.join(",");
+  }
+  /**
+   * Serializes an object cookie value as JSON.
+   * @param obj - The object to serialize
+   * @param param - The cookie parameter configuration
+   * @returns The JSON string representation of the object
+   */
+  serializeObject(obj, param) {
+    return JSON.stringify(obj);
+  }
+  /**
+   * Type guard to check if a value is a non-null object.
+   * @param value - The value to check
+   * @returns True if the value is an object and not null
+   */
+  isNonNullObject(value) {
+    return typeof value === "object" && value !== null;
+  }
+};
+
 // src/http/transport/request.ts
 var Request = class {
   constructor(params) {
@@ -1040,6 +1525,7 @@ var Request = class {
     this.headers = /* @__PURE__ */ new Map();
     this.queryParams = /* @__PURE__ */ new Map();
     this.pathParams = /* @__PURE__ */ new Map();
+    this.cookies = /* @__PURE__ */ new Map();
     this.validation = {};
     this.retry = {};
     this.baseUrl = params.baseUrl;
@@ -1051,6 +1537,7 @@ var Request = class {
     this.pathParams = params.pathParams;
     this.headers = params.headers;
     this.queryParams = params.queryParams;
+    this.cookies = params.cookies;
     this.responses = params.responses;
     this.errors = params.errors;
     this.requestSchema = params.requestSchema;
@@ -1063,6 +1550,12 @@ var Request = class {
     this.scopes = params.scopes;
     this.tokenManager = params.tokenManager;
   }
+  /**
+   * Adds a header parameter to the request with OpenAPI serialization rules.
+   *
+   * @param key - The header name
+   * @param param - The parameter configuration including value, style, and encoding options
+   */
   addHeaderParam(key, param) {
     if (param.value === void 0) {
       return;
@@ -1078,6 +1571,12 @@ var Request = class {
     }
     this.headers.set(key, param);
   }
+  /**
+   * Adds a query parameter to the request with OpenAPI serialization rules.
+   *
+   * @param key - The query parameter name
+   * @param param - The parameter configuration including value, style, and encoding options
+   */
   addQueryParam(key, param) {
     if (param.value === void 0) {
       return;
@@ -1093,6 +1592,12 @@ var Request = class {
     }
     this.queryParams.set(key, param);
   }
+  /**
+   * Adds a path parameter to the request with OpenAPI serialization rules.
+   *
+   * @param key - The path parameter name (matches template variable in path pattern)
+   * @param param - The parameter configuration including value, style, and encoding options
+   */
   addPathParam(key, param) {
     if (param.value === void 0) {
       return;
@@ -1108,26 +1613,50 @@ var Request = class {
     }
     this.pathParams.set(key, param);
   }
+  /**
+   * Sets the request body if the value is defined.
+   *
+   * @param body - The request body to send
+   */
   addBody(body) {
     if (body === void 0) {
       return;
     }
     this.body = body;
   }
+  /**
+   * Updates this request from a modified hook request.
+   * Used after hooks modify the request to sync changes back to the internal Request object.
+   *
+   * @param hookRequest - The modified request from hook processing
+   */
   updateFromHookRequest(hookRequest) {
     this.baseUrl = hookRequest.baseUrl;
     this.method = hookRequest.method;
     this.path = hookRequest.path;
     this.body = hookRequest.body;
   }
+  /**
+   * Constructs the complete URL by combining base URL, path with substituted parameters,
+   * and serialized query string.
+   *
+   * @returns The fully constructed URL ready for HTTP execution
+   */
   constructFullUrl() {
     const queryString = new QuerySerializer().serialize(this.queryParams);
     const path = this.constructPath();
     let baseUrl = this.baseUrl;
     return `${baseUrl}${path}${queryString}`;
   }
+  /**
+   * Creates a copy of this request with optional parameter overrides.
+   * Useful for pagination where you need to modify parameters while keeping the rest intact.
+   *
+   * @param overrides - Optional parameters to override in the copied request
+   * @returns A new Request instance with the specified overrides
+   */
   copy(overrides) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q;
     const createRequestParams = {
       baseUrl: (_a = overrides == null ? void 0 : overrides.baseUrl) != null ? _a : this.baseUrl,
       errors: (_b = overrides == null ? void 0 : overrides.errors) != null ? _b : this.errors,
@@ -1138,13 +1667,14 @@ var Request = class {
       pathParams: (_g = overrides == null ? void 0 : overrides.pathParams) != null ? _g : this.pathParams,
       queryParams: (_h = overrides == null ? void 0 : overrides.queryParams) != null ? _h : this.queryParams,
       headers: (_i = overrides == null ? void 0 : overrides.headers) != null ? _i : this.headers,
-      responses: (_j = overrides == null ? void 0 : overrides.responses) != null ? _j : this.responses,
-      requestSchema: (_k = overrides == null ? void 0 : overrides.requestSchema) != null ? _k : this.requestSchema,
-      requestContentType: (_l = overrides == null ? void 0 : overrides.requestContentType) != null ? _l : this.requestContentType,
-      retry: (_m = overrides == null ? void 0 : overrides.retry) != null ? _m : this.retry,
-      validation: (_n = overrides == null ? void 0 : overrides.validation) != null ? _n : this.validation,
-      filename: (_o = overrides == null ? void 0 : overrides.filename) != null ? _o : this.filename,
-      filenames: (_p = overrides == null ? void 0 : overrides.filenames) != null ? _p : this.filenames,
+      cookies: (_j = overrides == null ? void 0 : overrides.cookies) != null ? _j : this.cookies,
+      responses: (_k = overrides == null ? void 0 : overrides.responses) != null ? _k : this.responses,
+      requestSchema: (_l = overrides == null ? void 0 : overrides.requestSchema) != null ? _l : this.requestSchema,
+      requestContentType: (_m = overrides == null ? void 0 : overrides.requestContentType) != null ? _m : this.requestContentType,
+      retry: (_n = overrides == null ? void 0 : overrides.retry) != null ? _n : this.retry,
+      validation: (_o = overrides == null ? void 0 : overrides.validation) != null ? _o : this.validation,
+      filename: (_p = overrides == null ? void 0 : overrides.filename) != null ? _p : this.filename,
+      filenames: (_q = overrides == null ? void 0 : overrides.filenames) != null ? _q : this.filenames,
       scopes: overrides == null ? void 0 : overrides.scopes,
       tokenManager: this.tokenManager
     };
@@ -1153,12 +1683,34 @@ var Request = class {
       ...overrides
     });
   }
+  /**
+   * Serializes headers to a format suitable for HTTP execution.
+   *
+   * @returns Serialized headers as HeadersInit, or undefined if no headers
+   */
   getHeaders() {
     if (!this.headers || !this.headers.size) {
       return void 0;
     }
     return new HeaderSerializer().serialize(this.headers);
   }
+  /**
+   * Serializes cookies to a format suitable for HTTP execution.
+   *
+   * @returns Serialized cookies as a record, or undefined if no cookies
+   */
+  getCookies() {
+    if (!this.cookies || !this.cookies.size) {
+      return void 0;
+    }
+    return new CookieSerializer().serialize(this.cookies);
+  }
+  /**
+   * Advances pagination parameters to fetch the next page.
+   * Handles both cursor-based and limit-offset pagination strategies.
+   *
+   * @param cursor - The cursor value for cursor-based pagination (optional for limit-offset)
+   */
   nextPage(cursor) {
     if (!this.pagination) {
       return;
@@ -1200,6 +1752,9 @@ var Request = class {
     this.pathParams.forEach((val, _) => {
       allParams.push(val);
     });
+    this.cookies.forEach((val, _) => {
+      allParams.push(val);
+    });
     return allParams;
   }
 };
@@ -1212,6 +1767,10 @@ var Environment = /* @__PURE__ */ ((Environment2) => {
 
 // src/http/transport/request-builder.ts
 var RequestBuilder = class {
+  /**
+   * Creates a new request builder with default configuration.
+   * Initializes retry settings, validation options, and empty parameter collections.
+   */
   constructor() {
     this.params = {
       baseUrl: "https://api.celitech.net/v1" /* DEFAULT */,
@@ -1232,6 +1791,7 @@ var RequestBuilder = class {
       pathParams: /* @__PURE__ */ new Map(),
       queryParams: /* @__PURE__ */ new Map(),
       headers: /* @__PURE__ */ new Map(),
+      cookies: /* @__PURE__ */ new Map(),
       tokenManager: new OAuthTokenManager()
     };
   }
@@ -1429,9 +1989,37 @@ var RequestBuilder = class {
     });
     return this;
   }
+  addCookieParam(param) {
+    var _a, _b, _c;
+    if (param.value === void 0 || param.key === void 0) {
+      return this;
+    }
+    this.params.cookies.set(param.key, {
+      key: param.key,
+      value: param.value,
+      explode: (_a = param.explode) != null ? _a : true,
+      style: (_b = param.style) != null ? _b : "form" /* FORM */,
+      encode: (_c = param.encode) != null ? _c : false,
+      isLimit: !!param.isLimit,
+      isOffset: !!param.isOffset,
+      isCursor: !!param.isCursor
+    });
+    return this;
+  }
+  /**
+   * Builds and returns the configured Request object.
+   * Call this method after configuring all request parameters.
+   * @returns A new Request instance with all configured parameters
+   */
   build() {
     return new Request(this.params);
   }
+  /**
+   * Converts a string to Base64 encoding.
+   * Works in both Node.js and browser environments.
+   * @param str - The string to encode
+   * @returns The Base64-encoded string
+   */
   toBase64(str) {
     if (typeof window === "undefined") {
       return Buffer.from(str, "utf-8").toString("base64");
@@ -1530,11 +2118,22 @@ var GrantType = /* @__PURE__ */ ((GrantType2) => {
 
 // src/http/oauth/token-manager.ts
 var OAuthToken = class {
+  /**
+   * Creates a new OAuth token.
+   * @param accessToken - The access token string
+   * @param scopes - Set of OAuth scopes granted to this token
+   * @param expiresAt - Timestamp when the token expires (milliseconds since epoch), or null if no expiration
+   */
   constructor(accessToken, scopes, expiresAt) {
     this.accessToken = accessToken;
     this.scopes = scopes;
     this.expiresAt = expiresAt;
   }
+  /**
+   * Checks if this token has all the required scopes.
+   * @param scopes - Set of scopes to check for
+   * @returns True if the token has all required scopes, false otherwise
+   */
   hasAllScopes(scopes) {
     for (const scope of scopes) {
       if (!this.scopes.has(scope)) {
@@ -1545,6 +2144,14 @@ var OAuthToken = class {
   }
 };
 var OAuthTokenManager = class {
+  /**
+   * Gets a valid access token for the specified scopes.
+   * Returns a cached token if available and not expired, otherwise requests a new one.
+   * @param scopes - Set of OAuth scopes required for the token
+   * @param config - SDK configuration containing client credentials
+   * @returns A promise that resolves to a valid OAuth token
+   * @throws Error if client credentials are missing or token request fails
+   */
   async getToken(scopes, config) {
     var _a, _b, _c, _d, _e, _f;
     if (((_a = this.token) == null ? void 0 : _a.hasAllScopes(scopes)) && ((_b = this.token) == null ? void 0 : _b.expiresAt) && this.token.expiresAt - Date.now() > 5e3) {
@@ -1652,11 +2259,21 @@ var import_zod8 = require("zod");
 
 // src/http/errors/throwable-error.ts
 var ThrowableError = class extends Error {
+  /**
+   * Creates a new throwable error.
+   * @param message - The error message
+   * @param response - Optional response data associated with the error
+   */
   constructor(message, response) {
     super(message);
     this.message = message;
     this.response = response;
   }
+  /**
+   * Throws this error instance.
+   * Convenience method for explicitly throwing the error.
+   * @throws This error instance
+   */
   throw() {
     throw this;
   }
@@ -1744,6 +2361,7 @@ var packages = import_zod11.z.lazy(() => {
     destination: import_zod11.z.string(),
     destinationIso2: import_zod11.z.string(),
     dataLimitInBytes: import_zod11.z.number(),
+    dataLimitInGb: import_zod11.z.number(),
     minDays: import_zod11.z.number(),
     maxDays: import_zod11.z.number(),
     priceInCents: import_zod11.z.number()
@@ -1755,6 +2373,7 @@ var packagesResponse = import_zod11.z.lazy(() => {
     destination: import_zod11.z.string(),
     destinationISO2: import_zod11.z.string(),
     dataLimitInBytes: import_zod11.z.number(),
+    dataLimitInGB: import_zod11.z.number(),
     minDays: import_zod11.z.number(),
     maxDays: import_zod11.z.number(),
     priceInCents: import_zod11.z.number()
@@ -1763,6 +2382,7 @@ var packagesResponse = import_zod11.z.lazy(() => {
     destination: data["destination"],
     destinationIso2: data["destinationISO2"],
     dataLimitInBytes: data["dataLimitInBytes"],
+    dataLimitInGb: data["dataLimitInGB"],
     minDays: data["minDays"],
     maxDays: data["maxDays"],
     priceInCents: data["priceInCents"]
@@ -1774,6 +2394,7 @@ var packagesRequest = import_zod11.z.lazy(() => {
     destination: import_zod11.z.string(),
     destinationIso2: import_zod11.z.string(),
     dataLimitInBytes: import_zod11.z.number(),
+    dataLimitInGb: import_zod11.z.number(),
     minDays: import_zod11.z.number(),
     maxDays: import_zod11.z.number(),
     priceInCents: import_zod11.z.number()
@@ -1782,6 +2403,7 @@ var packagesRequest = import_zod11.z.lazy(() => {
     destination: data["destination"],
     destinationISO2: data["destinationIso2"],
     dataLimitInBytes: data["dataLimitInBytes"],
+    dataLimitInGB: data["dataLimitInGb"],
     minDays: data["minDays"],
     maxDays: data["maxDays"],
     priceInCents: data["priceInCents"]
@@ -1978,29 +2600,39 @@ var createPurchaseV2OkResponseProfile = import_zod16.z.lazy(() => {
   return import_zod16.z.object({
     iccid: import_zod16.z.string().min(18).max(22),
     activationCode: import_zod16.z.string().min(1e3).max(8e3),
-    manualActivationCode: import_zod16.z.string()
+    manualActivationCode: import_zod16.z.string(),
+    iosActivationLink: import_zod16.z.string(),
+    androidActivationLink: import_zod16.z.string()
   });
 });
 var createPurchaseV2OkResponseProfileResponse = import_zod16.z.lazy(() => {
   return import_zod16.z.object({
     iccid: import_zod16.z.string().min(18).max(22),
     activationCode: import_zod16.z.string().min(1e3).max(8e3),
-    manualActivationCode: import_zod16.z.string()
+    manualActivationCode: import_zod16.z.string(),
+    iosActivationLink: import_zod16.z.string(),
+    androidActivationLink: import_zod16.z.string()
   }).transform((data) => ({
     iccid: data["iccid"],
     activationCode: data["activationCode"],
-    manualActivationCode: data["manualActivationCode"]
+    manualActivationCode: data["manualActivationCode"],
+    iosActivationLink: data["iosActivationLink"],
+    androidActivationLink: data["androidActivationLink"]
   }));
 });
 var createPurchaseV2OkResponseProfileRequest = import_zod16.z.lazy(() => {
   return import_zod16.z.object({
     iccid: import_zod16.z.string().min(18).max(22),
     activationCode: import_zod16.z.string().min(1e3).max(8e3),
-    manualActivationCode: import_zod16.z.string()
+    manualActivationCode: import_zod16.z.string(),
+    iosActivationLink: import_zod16.z.string(),
+    androidActivationLink: import_zod16.z.string()
   }).transform((data) => ({
     iccid: data["iccid"],
     activationCode: data["activationCode"],
-    manualActivationCode: data["manualActivationCode"]
+    manualActivationCode: data["manualActivationCode"],
+    iosActivationLink: data["iosActivationLink"],
+    androidActivationLink: data["androidActivationLink"]
   }));
 });
 
@@ -2042,6 +2674,7 @@ var package_ = import_zod18.z.lazy(() => {
   return import_zod18.z.object({
     id: import_zod18.z.string(),
     dataLimitInBytes: import_zod18.z.number(),
+    dataLimitInGb: import_zod18.z.number(),
     destination: import_zod18.z.string(),
     destinationIso2: import_zod18.z.string(),
     destinationName: import_zod18.z.string(),
@@ -2052,6 +2685,7 @@ var packageResponse = import_zod18.z.lazy(() => {
   return import_zod18.z.object({
     id: import_zod18.z.string(),
     dataLimitInBytes: import_zod18.z.number(),
+    dataLimitInGB: import_zod18.z.number(),
     destination: import_zod18.z.string(),
     destinationISO2: import_zod18.z.string(),
     destinationName: import_zod18.z.string(),
@@ -2059,6 +2693,7 @@ var packageResponse = import_zod18.z.lazy(() => {
   }).transform((data) => ({
     id: data["id"],
     dataLimitInBytes: data["dataLimitInBytes"],
+    dataLimitInGb: data["dataLimitInGB"],
     destination: data["destination"],
     destinationIso2: data["destinationISO2"],
     destinationName: data["destinationName"],
@@ -2069,6 +2704,7 @@ var packageRequest = import_zod18.z.lazy(() => {
   return import_zod18.z.object({
     id: import_zod18.z.string(),
     dataLimitInBytes: import_zod18.z.number(),
+    dataLimitInGb: import_zod18.z.number(),
     destination: import_zod18.z.string(),
     destinationIso2: import_zod18.z.string(),
     destinationName: import_zod18.z.string(),
@@ -2076,6 +2712,7 @@ var packageRequest = import_zod18.z.lazy(() => {
   }).transform((data) => ({
     id: data["id"],
     dataLimitInBytes: data["dataLimitInBytes"],
+    dataLimitInGB: data["dataLimitInGb"],
     destination: data["destination"],
     destinationISO2: data["destinationIso2"],
     destinationName: data["destinationName"],
@@ -2651,24 +3288,29 @@ var import_zod32 = require("zod");
 var getPurchaseConsumptionOkResponse = import_zod32.z.lazy(() => {
   return import_zod32.z.object({
     dataUsageRemainingInBytes: import_zod32.z.number(),
+    dataUsageRemainingInGb: import_zod32.z.number(),
     status: import_zod32.z.string()
   });
 });
 var getPurchaseConsumptionOkResponseResponse = import_zod32.z.lazy(() => {
   return import_zod32.z.object({
     dataUsageRemainingInBytes: import_zod32.z.number(),
+    dataUsageRemainingInGB: import_zod32.z.number(),
     status: import_zod32.z.string()
   }).transform((data) => ({
     dataUsageRemainingInBytes: data["dataUsageRemainingInBytes"],
+    dataUsageRemainingInGb: data["dataUsageRemainingInGB"],
     status: data["status"]
   }));
 });
 var getPurchaseConsumptionOkResponseRequest = import_zod32.z.lazy(() => {
   return import_zod32.z.object({
     dataUsageRemainingInBytes: import_zod32.z.number(),
+    dataUsageRemainingInGb: import_zod32.z.number(),
     status: import_zod32.z.string()
   }).transform((data) => ({
     dataUsageRemainingInBytes: data["dataUsageRemainingInBytes"],
+    dataUsageRemainingInGB: data["dataUsageRemainingInGb"],
     status: data["status"]
   }));
 });