@unkey/api 2.0.0-alpha.7 → 2.0.0

package/src/models/components/keyresponsedata.ts

@@ -0,0 +1,171 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+import {
+  Identity,
+  Identity$inboundSchema,
+  Identity$Outbound,
+  Identity$outboundSchema,
+} from "./identity.js";
+import {
+  KeyCreditsData,
+  KeyCreditsData$inboundSchema,
+  KeyCreditsData$Outbound,
+  KeyCreditsData$outboundSchema,
+} from "./keycreditsdata.js";
+import {
+  RatelimitResponse,
+  RatelimitResponse$inboundSchema,
+  RatelimitResponse$Outbound,
+  RatelimitResponse$outboundSchema,
+} from "./ratelimitresponse.js";
+
+export type KeyResponseData = {
+  /**
+   * Unique identifier for this key.
+   */
+  keyId: string;
+  /**
+   * First few characters of the key for identification.
+   */
+  start: string;
+  /**
+   * Whether the key is enabled or disabled.
+   */
+  enabled: boolean;
+  /**
+   * Human-readable name for this key.
+   */
+  name?: string | undefined;
+  /**
+   * Custom metadata associated with this key.
+   */
+  meta?: { [k: string]: any } | undefined;
+  /**
+   * Unix timestamp in milliseconds when key was created.
+   */
+  createdAt: number;
+  /**
+   * Unix timestamp in milliseconds when key was last updated.
+   */
+  updatedAt?: number | undefined;
+  /**
+   * Unix timestamp in milliseconds when key expires (if set).
+   */
+  expires?: number | undefined;
+  /**
+   * External identifier linking this key to an entity in your system.
+   */
+  externalId?: string | undefined;
+  permissions?: Array<string> | undefined;
+  roles?: Array<string> | undefined;
+  /**
+   * Credit configuration and remaining balance for this key.
+   */
+  credits?: KeyCreditsData | undefined;
+  identity?: Identity | undefined;
+  /**
+   * Decrypted key value (only when decrypt=true).
+   */
+  plaintext?: string | undefined;
+  ratelimits?: Array<RatelimitResponse> | undefined;
+};
+
+/** @internal */
+export const KeyResponseData$inboundSchema: z.ZodType<
+  KeyResponseData,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  keyId: z.string(),
+  start: z.string(),
+  enabled: z.boolean(),
+  name: z.string().optional(),
+  meta: z.record(z.any()).optional(),
+  createdAt: z.number().int(),
+  updatedAt: z.number().int().optional(),
+  expires: z.number().int().optional(),
+  externalId: z.string().optional(),
+  permissions: z.array(z.string()).optional(),
+  roles: z.array(z.string()).optional(),
+  credits: KeyCreditsData$inboundSchema.optional(),
+  identity: Identity$inboundSchema.optional(),
+  plaintext: z.string().optional(),
+  ratelimits: z.array(RatelimitResponse$inboundSchema).optional(),
+});
+
+/** @internal */
+export type KeyResponseData$Outbound = {
+  keyId: string;
+  start: string;
+  enabled: boolean;
+  name?: string | undefined;
+  meta?: { [k: string]: any } | undefined;
+  createdAt: number;
+  updatedAt?: number | undefined;
+  expires?: number | undefined;
+  externalId?: string | undefined;
+  permissions?: Array<string> | undefined;
+  roles?: Array<string> | undefined;
+  credits?: KeyCreditsData$Outbound | undefined;
+  identity?: Identity$Outbound | undefined;
+  plaintext?: string | undefined;
+  ratelimits?: Array<RatelimitResponse$Outbound> | undefined;
+};
+
+/** @internal */
+export const KeyResponseData$outboundSchema: z.ZodType<
+  KeyResponseData$Outbound,
+  z.ZodTypeDef,
+  KeyResponseData
+> = z.object({
+  keyId: z.string(),
+  start: z.string(),
+  enabled: z.boolean(),
+  name: z.string().optional(),
+  meta: z.record(z.any()).optional(),
+  createdAt: z.number().int(),
+  updatedAt: z.number().int().optional(),
+  expires: z.number().int().optional(),
+  externalId: z.string().optional(),
+  permissions: z.array(z.string()).optional(),
+  roles: z.array(z.string()).optional(),
+  credits: KeyCreditsData$outboundSchema.optional(),
+  identity: Identity$outboundSchema.optional(),
+  plaintext: z.string().optional(),
+  ratelimits: z.array(RatelimitResponse$outboundSchema).optional(),
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace KeyResponseData$ {
+  /** @deprecated use `KeyResponseData$inboundSchema` instead. */
+  export const inboundSchema = KeyResponseData$inboundSchema;
+  /** @deprecated use `KeyResponseData$outboundSchema` instead. */
+  export const outboundSchema = KeyResponseData$outboundSchema;
+  /** @deprecated use `KeyResponseData$Outbound` instead. */
+  export type Outbound = KeyResponseData$Outbound;
+}
+
+export function keyResponseDataToJSON(
+  keyResponseData: KeyResponseData,
+): string {
+  return JSON.stringify(KeyResponseData$outboundSchema.parse(keyResponseData));
+}
+
+export function keyResponseDataFromJSON(
+  jsonString: string,
+): SafeParseResult<KeyResponseData, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => KeyResponseData$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'KeyResponseData' from JSON`,
+  );
+}

package/src/models/components/keysverifykeycredits.ts

@@ -0,0 +1,81 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+/**
+ * Controls credit consumption for usage-based billing and quota enforcement.
+ *
+ * @remarks
+ * Omitting this field uses the default cost of 1 credit per verification.
+ * Credits provide globally consistent usage tracking, essential for paid APIs with strict quotas.
+ */
+export type KeysVerifyKeyCredits = {
+  /**
+   * Sets how many credits to deduct for this verification request.
+   *
+   * @remarks
+   * Use 0 for read-only operations or free tier access, higher values for premium features.
+   * Credits are deducted after all security checks pass.
+   * Essential for implementing usage-based pricing with different operation costs.
+   */
+  cost: number;
+};
+
+/** @internal */
+export const KeysVerifyKeyCredits$inboundSchema: z.ZodType<
+  KeysVerifyKeyCredits,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  cost: z.number().int(),
+});
+
+/** @internal */
+export type KeysVerifyKeyCredits$Outbound = {
+  cost: number;
+};
+
+/** @internal */
+export const KeysVerifyKeyCredits$outboundSchema: z.ZodType<
+  KeysVerifyKeyCredits$Outbound,
+  z.ZodTypeDef,
+  KeysVerifyKeyCredits
+> = z.object({
+  cost: z.number().int(),
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace KeysVerifyKeyCredits$ {
+  /** @deprecated use `KeysVerifyKeyCredits$inboundSchema` instead. */
+  export const inboundSchema = KeysVerifyKeyCredits$inboundSchema;
+  /** @deprecated use `KeysVerifyKeyCredits$outboundSchema` instead. */
+  export const outboundSchema = KeysVerifyKeyCredits$outboundSchema;
+  /** @deprecated use `KeysVerifyKeyCredits$Outbound` instead. */
+  export type Outbound = KeysVerifyKeyCredits$Outbound;
+}
+
+export function keysVerifyKeyCreditsToJSON(
+  keysVerifyKeyCredits: KeysVerifyKeyCredits,
+): string {
+  return JSON.stringify(
+    KeysVerifyKeyCredits$outboundSchema.parse(keysVerifyKeyCredits),
+  );
+}
+
+export function keysVerifyKeyCreditsFromJSON(
+  jsonString: string,
+): SafeParseResult<KeysVerifyKeyCredits, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => KeysVerifyKeyCredits$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'KeysVerifyKeyCredits' from JSON`,
+  );
+}

package/src/models/components/keysverifykeyratelimit.ts

@@ -0,0 +1,90 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type KeysVerifyKeyRatelimit = {
+  /**
+   * References an existing ratelimit by its name. Key Ratelimits will take precedence over identifier-based limits.
+   */
+  name: string;
+  /**
+   * Optionally override how expensive this operation is and how many tokens are deducted from the current limit.
+   */
+  cost?: number | undefined;
+  /**
+   * Optionally override the maximum number of requests allowed within the specified interval.
+   */
+  limit?: number | undefined;
+  /**
+   * Optionally override the duration of the rate limit window duration.
+   */
+  duration?: number | undefined;
+};
+
+/** @internal */
+export const KeysVerifyKeyRatelimit$inboundSchema: z.ZodType<
+  KeysVerifyKeyRatelimit,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  name: z.string(),
+  cost: z.number().int().default(1),
+  limit: z.number().int().optional(),
+  duration: z.number().int().optional(),
+});
+
+/** @internal */
+export type KeysVerifyKeyRatelimit$Outbound = {
+  name: string;
+  cost: number;
+  limit?: number | undefined;
+  duration?: number | undefined;
+};
+
+/** @internal */
+export const KeysVerifyKeyRatelimit$outboundSchema: z.ZodType<
+  KeysVerifyKeyRatelimit$Outbound,
+  z.ZodTypeDef,
+  KeysVerifyKeyRatelimit
+> = z.object({
+  name: z.string(),
+  cost: z.number().int().default(1),
+  limit: z.number().int().optional(),
+  duration: z.number().int().optional(),
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace KeysVerifyKeyRatelimit$ {
+  /** @deprecated use `KeysVerifyKeyRatelimit$inboundSchema` instead. */
+  export const inboundSchema = KeysVerifyKeyRatelimit$inboundSchema;
+  /** @deprecated use `KeysVerifyKeyRatelimit$outboundSchema` instead. */
+  export const outboundSchema = KeysVerifyKeyRatelimit$outboundSchema;
+  /** @deprecated use `KeysVerifyKeyRatelimit$Outbound` instead. */
+  export type Outbound = KeysVerifyKeyRatelimit$Outbound;
+}
+
+export function keysVerifyKeyRatelimitToJSON(
+  keysVerifyKeyRatelimit: KeysVerifyKeyRatelimit,
+): string {
+  return JSON.stringify(
+    KeysVerifyKeyRatelimit$outboundSchema.parse(keysVerifyKeyRatelimit),
+  );
+}
+
+export function keysVerifyKeyRatelimitFromJSON(
+  jsonString: string,
+): SafeParseResult<KeysVerifyKeyRatelimit, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => KeysVerifyKeyRatelimit$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'KeysVerifyKeyRatelimit' from JSON`,
+  );
+}

package/src/models/components/meta.ts

@@ -7,9 +7,12 @@ import { safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
+/**
+ * Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
+ */
 export type Meta = {
   /**
-   * A unique id for this request. Please always provide this to support.
+   * A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
    */
   requestId: string;
 };

package/src/models/components/pagination.ts

@@ -7,15 +7,26 @@ import { safeParse } from "../../lib/schemas.js";
 import { Result as SafeParseResult } from "../../types/fp.js";
 import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
+/**
+ * Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
+ */
 export type Pagination = {
   /**
-   * Opaque token for retrieving the next set of results
+   * Opaque pagination token for retrieving the next page of results.
+   *
+   * @remarks
+   * Include this exact value in the cursor field of subsequent requests.
+   * Cursors are temporary and may expire after extended periods.
    */
   cursor?: string | undefined;
   /**
-   * Indicates if more results exist beyond this page
+   * Indicates whether additional results exist beyond this page.
+   *
+   * @remarks
+   * When true, use the cursor to fetch the next page.
+   * When false, you have reached the end of the result set.
    */
-  hasMore?: boolean | undefined;
+  hasMore: boolean;
 };
 
 /** @internal */
@@ -25,13 +36,13 @@ export const Pagination$inboundSchema: z.ZodType<
   unknown
 > = z.object({
   cursor: z.string().optional(),
-  hasMore: z.boolean().optional(),
+  hasMore: z.boolean(),
 });
 
 /** @internal */
 export type Pagination$Outbound = {
   cursor?: string | undefined;
-  hasMore?: boolean | undefined;
+  hasMore: boolean;
 };
 
 /** @internal */
@@ -41,7 +52,7 @@ export const Pagination$outboundSchema: z.ZodType<
   Pagination
 > = z.object({
   cursor: z.string().optional(),
-  hasMore: z.boolean().optional(),
+  hasMore: z.boolean(),
 });
 
 /**

package/src/models/components/permission.ts

@@ -0,0 +1,100 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+import { safeParse } from "../../lib/schemas.js";
+import { Result as SafeParseResult } from "../../types/fp.js";
+import { SDKValidationError } from "../errors/sdkvalidationerror.js";
+
+export type Permission = {
+  /**
+   * The unique identifier for this permission within Unkey's system.
+   *
+   * @remarks
+   * Generated automatically when the permission is created and used to reference this permission in API operations.
+   * Always begins with 'perm_' followed by alphanumeric characters and underscores.
+   */
+  id: string;
+  /**
+   * The human-readable name for this permission that describes its purpose.
+   *
+   * @remarks
+   * Should be descriptive enough for developers to understand what access it grants.
+   * Use clear, semantic names that reflect the resources or actions being permitted.
+   * Names must be unique within your workspace to avoid confusion and conflicts.
+   */
+  name: string;
+  /**
+   * The URL-safe identifier when this permission was created.
+   */
+  slug: string;
+  /**
+   * Optional detailed explanation of what this permission grants access to.
+   *
+   * @remarks
+   * Helps team members understand the scope and implications of granting this permission.
+   * Include information about what resources can be accessed and what actions can be performed.
+   * Not visible to end users - this is for internal documentation and team clarity.
+   */
+  description?: string | undefined;
+};
+
+/** @internal */
+export const Permission$inboundSchema: z.ZodType<
+  Permission,
+  z.ZodTypeDef,
+  unknown
+> = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().optional(),
+});
+
+/** @internal */
+export type Permission$Outbound = {
+  id: string;
+  name: string;
+  slug: string;
+  description?: string | undefined;
+};
+
+/** @internal */
+export const Permission$outboundSchema: z.ZodType<
+  Permission$Outbound,
+  z.ZodTypeDef,
+  Permission
+> = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string().optional(),
+});
+
+/**
+ * @internal
+ * @deprecated This namespace will be removed in future versions. Use schemas and types that are exported directly from this module.
+ */
+export namespace Permission$ {
+  /** @deprecated use `Permission$inboundSchema` instead. */
+  export const inboundSchema = Permission$inboundSchema;
+  /** @deprecated use `Permission$outboundSchema` instead. */
+  export const outboundSchema = Permission$outboundSchema;
+  /** @deprecated use `Permission$Outbound` instead. */
+  export type Outbound = Permission$Outbound;
+}
+
+export function permissionToJSON(permission: Permission): string {
+  return JSON.stringify(Permission$outboundSchema.parse(permission));
+}
+
+export function permissionFromJSON(
+  jsonString: string,
+): SafeParseResult<Permission, SDKValidationError> {
+  return safeParse(
+    jsonString,
+    (x) => Permission$inboundSchema.parse(JSON.parse(x)),
+    `Failed to parse 'Permission' from JSON`,
+  );
+}

package/src/models/components/ratelimitoverride.ts

@@ -9,23 +9,40 @@ import { SDKValidationError } from "../errors/sdkvalidationerror.js";
 
 export type RatelimitOverride = {
   /**
-   * The id of the namespace.
-   */
-  namespaceId: string;
-  /**
-   * The id of the override.
+   * The unique identifier of this specific rate limit override. This ID is generated when the override is created and can be used for management operations like updating or deleting the override.
    */
   overrideId: string;
   /**
-   * The duration in milliseconds for the rate limit window.
+   * The duration in milliseconds for this override's rate limit window. This may differ from the default duration for the namespace, allowing custom time windows for specific entities. After this duration elapses, the rate limit counter for affected identifiers resets to zero.
    */
   duration: number;
   /**
-   * Identifier of your user, this can be their userId, an email, an ip or anything else. Wildcards ( * ) can be used to match multiple identifiers, More info can be found at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
+   * The identifier pattern this override applies to. This determines which entities receive the custom rate limit.
+   *
+   * @remarks
+   *
+   * This can be:
+   * - An exact identifier for a specific entity
+   * - A pattern with wildcards for matching multiple entities
+   *
+   * Wildcard examples:
+   * - 'admin_*' matches any identifier starting with 'admin_'
+   * - '*_test' matches any identifier ending with '_test'
+   * - '*premium*' matches any identifier containing 'premium'
+   *
+   * More complex patterns can combine multiple wildcards. Detailed documentation on pattern matching rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules
    */
   identifier: string;
   /**
-   * The maximum number of requests allowed.
+   * The maximum number of requests allowed for entities matching this override. This replaces the default limit for the namespace when applied.
+   *
+   * @remarks
+   *
+   * Common use cases:
+   * - Higher limits for premium customers
+   * - Reduced limits for abusive or suspicious entities
+   * - Zero limit to completely block specific patterns
+   * - Custom tier-based limits for different customer segments
    */
   limit: number;
 };
@@ -36,7 +53,6 @@ export const RatelimitOverride$inboundSchema: z.ZodType<
   z.ZodTypeDef,
   unknown
 > = z.object({
-  namespaceId: z.string(),
   overrideId: z.string(),
   duration: z.number().int(),
   identifier: z.string(),
@@ -45,7 +61,6 @@ export const RatelimitOverride$inboundSchema: z.ZodType<
 
 /** @internal */
 export type RatelimitOverride$Outbound = {
-  namespaceId: string;
   overrideId: string;
   duration: number;
   identifier: string;
@@ -58,7 +73,6 @@ export const RatelimitOverride$outboundSchema: z.ZodType<
   z.ZodTypeDef,
   RatelimitOverride
 > = z.object({
-  namespaceId: z.string(),
   overrideId: z.string(),
   duration: z.number().int(),
   identifier: z.string(),