@unkey/api/src/funcs/keysUpdateCredits.ts

Developer-friendly & type-safe Typescript SDK specifically catered to leverage *@unkey/api* API.

/*
 * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
 */

import { UnkeyCore } from "../core.js";
import { encodeJSON } from "../lib/encodings.js";
import { matchStatusCode } from "../lib/http.js";
import * as M from "../lib/matchers.js";
import { compactMap } from "../lib/primitives.js";
import { safeParse } from "../lib/schemas.js";
import { RequestOptions } from "../lib/sdks.js";
import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
import { pathToFunc } from "../lib/url.js";
import * as components from "../models/components/index.js";
import {
  ConnectionError,
  InvalidRequestError,
  RequestAbortedError,
  RequestTimeoutError,
  UnexpectedClientError,
} from "../models/errors/httpclienterrors.js";
import * as errors from "../models/errors/index.js";
import { ResponseValidationError } from "../models/errors/responsevalidationerror.js";
import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
import { UnkeyError } from "../models/errors/unkeyerror.js";
import { APICall, APIPromise } from "../types/async.js";
import { Result } from "../types/fp.js";

/**
 * Update key credits
 *
 * @remarks
 * Update credit quotas in response to plan changes, billing cycles, or usage purchases.
 *
 * Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage.
 *
 * **Important**: Setting unlimited credits automatically clears existing refill configurations.
 *
 * **Required Permissions**
 *
 * Your root key must have one of the following permissions:
 * - `api.*.update_key` (to update keys in any API)
 * - `api.<api_id>.update_key` (to update keys in a specific API)
 *
 * **Side Effects**
 *
 * Credit updates remove the key from cache immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes take effect instantly but may take up to 30 seconds to propagate to all edge regions.
 *
 * If set, this operation will use {@link Security.rootKey} from the global security.
 */
export function keysUpdateCredits(
  client: UnkeyCore,
  request: components.V2KeysUpdateCreditsRequestBody,
  options?: RequestOptions,
): APIPromise<
  Result<
    components.V2KeysUpdateCreditsResponseBody,
    | errors.BadRequestErrorResponse
    | errors.UnauthorizedErrorResponse
    | errors.ForbiddenErrorResponse
    | errors.NotFoundErrorResponse
    | errors.TooManyRequestsErrorResponse
    | errors.InternalServerErrorResponse
    | UnkeyError
    | ResponseValidationError
    | ConnectionError
    | RequestAbortedError
    | RequestTimeoutError
    | InvalidRequestError
    | UnexpectedClientError
    | SDKValidationError
  >
> {
  return new APIPromise($do(
    client,
    request,
    options,
  ));
}

async function $do(
  client: UnkeyCore,
  request: components.V2KeysUpdateCreditsRequestBody,
  options?: RequestOptions,
): Promise<
  [
    Result<
      components.V2KeysUpdateCreditsResponseBody,
      | errors.BadRequestErrorResponse
      | errors.UnauthorizedErrorResponse
      | errors.ForbiddenErrorResponse
      | errors.NotFoundErrorResponse
      | errors.TooManyRequestsErrorResponse
      | errors.InternalServerErrorResponse
      | UnkeyError
      | ResponseValidationError
      | ConnectionError
      | RequestAbortedError
      | RequestTimeoutError
      | InvalidRequestError
      | UnexpectedClientError
      | SDKValidationError
    >,
    APICall,
  ]
> {
  const parsed = safeParse(
    request,
    (value) =>
      components.V2KeysUpdateCreditsRequestBody$outboundSchema.parse(value),
    "Input validation failed",
  );
  if (!parsed.ok) {
    return [parsed, { status: "invalid" }];
  }
  const payload = parsed.value;
  const body = encodeJSON("body", payload, { explode: true });

  const path = pathToFunc("/v2/keys.updateCredits")();

  const headers = new Headers(compactMap({
    "Content-Type": "application/json",
    Accept: "application/json",
  }));

  const secConfig = await extractSecurity(client._options.rootKey);
  const securityInput = secConfig == null ? {} : { rootKey: secConfig };
  const requestSecurity = resolveGlobalSecurity(securityInput, [0]);

  const context = {
    options: client._options,
    baseURL: options?.serverURL ?? client._baseURL ?? "",
    operationID: "keys.updateCredits",
    oAuth2Scopes: null,

    resolvedSecurity: requestSecurity,

    securitySource: client._options.rootKey,
    retryConfig: options?.retries
      || client._options.retryConfig
      || {
        strategy: "backoff",
        backoff: {
          initialInterval: 50,
          maxInterval: 1000,
          exponent: 1.5,
          maxElapsedTime: 10000,
        },
        retryConnectionErrors: true,
      }
      || { strategy: "none" },
    retryCodes: options?.retryCodes || ["5XX"],
  };

  const requestRes = client._createRequest(context, {
    security: requestSecurity,
    method: "POST",
    baseURL: options?.serverURL,
    path: path,
    headers: headers,
    body: body,
    userAgent: client._options.userAgent,
    timeoutMs: options?.timeoutMs || client._options.timeoutMs || -1,
  }, options);
  if (!requestRes.ok) {
    return [requestRes, { status: "invalid" }];
  }
  const req = requestRes.value;

  const doResult = await client._do(req, {
    context,
    isErrorStatusCode: (statusCode: number) =>
      matchStatusCode({ status: statusCode } as Response, ["4XX", "5XX"]),
    retryConfig: context.retryConfig,
    retryCodes: context.retryCodes,
  });
  if (!doResult.ok) {
    return [doResult, { status: "request-error", request: req }];
  }
  const response = doResult.value;

  const responseFields = {
    HttpMeta: { Response: response, Request: req },
  };

  const [result] = await M.match<
    components.V2KeysUpdateCreditsResponseBody,
    | errors.BadRequestErrorResponse
    | errors.UnauthorizedErrorResponse
    | errors.ForbiddenErrorResponse
    | errors.NotFoundErrorResponse
    | errors.TooManyRequestsErrorResponse
    | errors.InternalServerErrorResponse
    | UnkeyError
    | ResponseValidationError
    | ConnectionError
    | RequestAbortedError
    | RequestTimeoutError
    | InvalidRequestError
    | UnexpectedClientError
    | SDKValidationError
  >(
    M.json(200, components.V2KeysUpdateCreditsResponseBody$inboundSchema),
    M.jsonErr(400, errors.BadRequestErrorResponse$inboundSchema),
    M.jsonErr(401, errors.UnauthorizedErrorResponse$inboundSchema),
    M.jsonErr(403, errors.ForbiddenErrorResponse$inboundSchema),
    M.jsonErr(404, errors.NotFoundErrorResponse$inboundSchema),
    M.jsonErr(429, errors.TooManyRequestsErrorResponse$inboundSchema, {
      ctype: "application/problem+json",
    }),
    M.jsonErr(500, errors.InternalServerErrorResponse$inboundSchema),
    M.fail("4XX"),
    M.fail("5XX"),
  )(response, req, { extraFields: responseFields });
  if (!result.ok) {
    return [result, { status: "complete", request: req, response }];
  }

  return [result, { status: "complete", request: req, response }];
}