fix: add JSDoc docstrings from OpenAPI spec to all resource methods

src/admin-portal/admin-portal.ts

@@ -1,9 +1,22 @@
+// This file is auto-generated by oagen. Do not edit.
+
 import { WorkOS } from '../workos';
 import { GenerateLinkIntent } from '../common/interfaces';
 
 export class AdminPortal {
   constructor(private readonly workos: WorkOS) {}
 
+  /**
+   * Generate a Portal Link
+   *
+   * Generate a Portal Link scoped to an Organization.
+   * @param payload - Object containing organization.
+   * @returns {Promise<{ link: string; }>}
+   * @throws {BadRequestException} 400
+   * @throws 403 response from the API.
+   * @throws {NotFoundException} 404
+   * @throws {UnprocessableEntityException} 422
+   */
   async generateLink({
     intent,
     organization,

src/api-keys/api-keys.ts

@@ -1,3 +1,5 @@
+// This file is auto-generated by oagen. Do not edit.
+
 import { AutoPaginatable } from '../common/utils/pagination';
 import { WorkOS } from '../workos';
 import {
@@ -25,6 +27,15 @@ import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize';
 export class ApiKeys {
   constructor(private readonly workos: WorkOS) {}
 
+  /**
+   * Validate API key
+   *
+   * Validate an API key value and return the API key object if valid.
+   * @param payload - Object containing value.
+   * @returns {Promise<ApiKeyValidationResponse>}
+   * @throws {UnauthorizedException} 401
+   * @throws {UnprocessableEntityException} 422
+   */
   async createValidation(
     payload: ValidateApiKeyOptions,
   ): Promise<ValidateApiKeyResponse> {
@@ -36,10 +47,35 @@ export class ApiKeys {
     return deserializeValidateApiKeyResponse(data);
   }
 
+  /**
+   * Delete an API key
+   *
+   * Permanently deletes an API key. This action cannot be undone. Once deleted, any requests using this API key will fail authentication.
+   * @param id - The unique ID of the API key.
+   *
+   * @example
+   * "api_key_01EHZNVPK3SFK441A1RGBFSHRT"
+   *
+   * @returns {Promise<void>}
+   * @throws {NotFoundException} 404
+   */
   async deleteApiKey(id: string): Promise<void> {
     await this.workos.delete(`/api_keys/${id}`);
   }
 
+  /**
+   * List API keys for an organization
+   *
+   * Get a list of all API keys for an organization.
+   * @param organizationId - Unique identifier of the Organization.
+   *
+   * @example
+   * "org_01EHZNVPK3SFK441A1RGBFSHRT"
+   *
+   * @param options - Pagination and filter options.
+   * @returns {Promise<AutoPaginatable<ApiKey>>}
+   * @throws {NotFoundException} 404
+   */
   async listOrganizationApiKeys(
     options: ListOrganizationApiKeysOptions,
   ): Promise<AutoPaginatable<ApiKey>> {
@@ -63,6 +99,20 @@ export class ApiKeys {
     );
   }
 
+  /**
+   * Create an API key for an organization
+   *
+   * Create a new API key for an organization.
+   * @param organizationId - Unique identifier of the Organization.
+   *
+   * @example
+   * "org_01EHZNVPK3SFK441A1RGBFSHRT"
+   *
+   * @param options - Object containing name.
+   * @returns {Promise<ApiKeyWithValue>}
+   * @throws {NotFoundException} 404
+   * @throws {UnprocessableEntityException} 422
+   */
   async createOrganizationApiKey(
     options: CreateOrganizationApiKeyOptions,
     requestOptions: CreateOrganizationApiKeyRequestOptions = {},

src/api-keys/interfaces/api-key.interface.ts

@@ -1,15 +1,25 @@
+/** The API Key object if the value is valid, or `null` if invalid. */
 export interface ApiKey {
+  /** Distinguishes the API Key object. */
   object: 'api_key';
+  /** Unique identifier of the API Key. */
   id: string;
+  /** The entity that owns the API Key. */
   owner: {
     type: 'organization';
     id: string;
   };
+  /** A descriptive name for the API Key. */
   name: string;
+  /** An obfuscated representation of the API Key value. */
   obfuscatedValue: string;
+  /** Timestamp of when the API Key was last used. */
   lastUsedAt: string | null;
+  /** The permission slugs assigned to the API Key. */
   permissions: string[];
+  /** An ISO 8601 timestamp. */
   createdAt: string;
+  /** An ISO 8601 timestamp. */
   updatedAt: string;
 }
 

src/audit-logs/audit-logs.ts

@@ -25,6 +25,23 @@ import {
 export class AuditLogs {
   constructor(private readonly workos: WorkOS) {}
 
+  /**
+   * Create Event
+   *
+   * Create an Audit Log Event.
+   *
+   * This API supports idempotency which guarantees that performing the same operation multiple times will have the same result as if the operation were performed only once. This is handy in situations where you may need to retry a request due to a failure or prevent accidental duplicate requests from creating more than one resource.
+   *
+   * To achieve idempotency, you can add `Idempotency-Key` request header to a Create Event request with a unique string as the value. Each subsequent request matching this unique string will return the same response. We suggest using [v4 UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier) for idempotency keys to avoid collisions.
+   *
+   * Idempotency keys expire after 24 hours. The API will generate a new response if you submit a request with an expired key.
+   * @param payload - Object containing organizationId, event.
+   * @returns {Promise<void>}
+   * @throws {BadRequestException} 400
+   * @throws {NotFoundException} 404
+   * @throws {UnprocessableEntityException} 422
+   * @throws {RateLimitExceededException} 429
+   */
   async createEvent(
     organization: string,
     event: CreateAuditLogEventOptions,
@@ -48,6 +65,14 @@ export class AuditLogs {
     );
   }
 
+  /**
+   * Create Export
+   *
+   * Create an Audit Log Export. Exports are scoped to a single organization within a specified date range.
+   * @param payload - Object containing organizationId, rangeStart, rangeEnd.
+   * @returns {Promise<AuditLogExport>}
+   * @throws {BadRequestException} 400
+   */
   async createExport(options: AuditLogExportOptions): Promise<AuditLogExport> {
     const { data } = await this.workos.post<AuditLogExportResponse>(
       '/audit_logs/exports',
@@ -57,6 +82,18 @@ export class AuditLogs {
     return deserializeAuditLogExport(data);
   }
 
+  /**
+   * Get Export
+   *
+   * Get an Audit Log Export. The URL will expire after 10 minutes. If the export is needed again at a later time, refetching the export will regenerate the URL.
+   * @param auditLogExportId - The unique ID of the Audit Log Export.
+   *
+   * @example
+   * "audit_log_export_01GBZK5MP7TD1YCFQHFR22180V"
+   *
+   * @returns {Promise<AuditLogExport>}
+   * @throws {NotFoundException} 404
+   */
   async getExport(auditLogExportId: string): Promise<AuditLogExport> {
     const { data } = await this.workos.get<AuditLogExportResponse>(
       `/audit_logs/exports/${auditLogExportId}`,
@@ -65,6 +102,14 @@ export class AuditLogs {
     return deserializeAuditLogExport(data);
   }
 
+  /**
+   * Create Schema
+   *
+   * Creates a new Audit Log schema used to validate the payload of incoming Audit Log Events. If the `action` does not exist, it will also be created.
+   * @param payload - Object containing targets.
+   * @returns {Promise<AuditLogSchema>}
+   * @throws {UnprocessableEntityException} 422
+   */
   async createSchema(
     schema: CreateAuditLogSchemaOptions,
     options: CreateAuditLogSchemaRequestOptions = {},