From 0352bdf0111e68ad33398096e4a2bc1d2e968287 Mon Sep 17 00:00:00 2001 From: "Garen J. Torikian" Date: Tue, 21 Apr 2026 12:15:25 -0400 Subject: [PATCH 1/5] fix: add JSDoc docstrings from OpenAPI spec to all resource methods --- src/admin-portal/admin-portal.ts | 13 + src/api-keys/api-keys.ts | 41 ++ src/api-keys/interfaces/api-key.interface.ts | 10 + src/audit-logs/audit-logs.ts | 42 ++ src/authorization/authorization.ts | 453 ++++++++++++++++++ .../authorization-resource.interface.ts | 10 + ...berships-for-resource-options.interface.ts | 2 + .../interfaces/role-assignment.interface.ts | 6 + src/directory-sync/directory-sync.ts | 65 +++ .../interfaces/directory.interface.ts | 10 + .../list-directories-options.interface.ts | 2 + src/events/events.ts | 9 + src/feature-flags/feature-flags.ts | 75 +++ .../interfaces/feature-flag.interface.ts | 10 + src/multi-factor-auth/multi-factor-auth.ts | 65 +++ .../organization-domain.interface.ts | 10 + .../organization-domains.ts | 35 ++ .../list-organizations-options.interface.ts | 1 + .../interfaces/organization.interface.ts | 13 + src/organizations/organizations.ts | 57 +++ src/sso/interfaces/connection.interface.ts | 8 + .../list-connections-options.interface.ts | 3 + src/sso/interfaces/profile.interface.ts | 13 + src/sso/sso.ts | 37 ++ .../email-verification.interface.ts | 8 + .../interfaces/invitation.interface.ts | 14 + .../list-invitations-options.interface.ts | 2 + .../list-users-options.interface.ts | 2 + .../interfaces/magic-auth.interface.ts | 8 + .../organization-membership.interface.ts | 2 + .../interfaces/password-reset.interface.ts | 8 + .../interfaces/user.interface.ts | 14 + src/user-management/user-management.ts | 275 +++++++++++ src/widgets/widgets.ts | 10 + 34 files changed, 1333 insertions(+) diff --git a/src/admin-portal/admin-portal.ts b/src/admin-portal/admin-portal.ts index 343da4dc9..3623ba317 100644 --- a/src/admin-portal/admin-portal.ts +++ b/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, diff --git a/src/api-keys/api-keys.ts b/src/api-keys/api-keys.ts index 8230d3da7..4c1f2cc5f 100644 --- a/src/api-keys/api-keys.ts +++ b/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} + * @throws {UnauthorizedException} 401 + * @throws {UnprocessableEntityException} 422 + */ async createValidation( payload: ValidateApiKeyOptions, ): Promise { @@ -36,10 +47,29 @@ 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} + * @throws {NotFoundException} 404 + */ async deleteApiKey(id: string): Promise { 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>} + * @throws {NotFoundException} 404 + */ async listOrganizationApiKeys( options: ListOrganizationApiKeysOptions, ): Promise> { @@ -63,6 +93,17 @@ 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} + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async createOrganizationApiKey( options: CreateOrganizationApiKeyOptions, requestOptions: CreateOrganizationApiKeyRequestOptions = {}, diff --git a/src/api-keys/interfaces/api-key.interface.ts b/src/api-keys/interfaces/api-key.interface.ts index 8aee8403c..2ed911964 100644 --- a/src/api-keys/interfaces/api-key.interface.ts +++ b/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; } diff --git a/src/audit-logs/audit-logs.ts b/src/audit-logs/audit-logs.ts index 105d72e4d..bc072edd0 100644 --- a/src/audit-logs/audit-logs.ts +++ b/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} + * @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} + * @throws {BadRequestException} 400 + */ async createExport(options: AuditLogExportOptions): Promise { const { data } = await this.workos.post( '/audit_logs/exports', @@ -57,6 +82,15 @@ 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} + * @throws {NotFoundException} 404 + */ async getExport(auditLogExportId: string): Promise { const { data } = await this.workos.get( `/audit_logs/exports/${auditLogExportId}`, @@ -65,6 +99,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} + * @throws {UnprocessableEntityException} 422 + */ async createSchema( schema: CreateAuditLogSchemaOptions, options: CreateAuditLogSchemaRequestOptions = {}, diff --git a/src/authorization/authorization.ts b/src/authorization/authorization.ts index 9981ccc8e..61c810d79 100644 --- a/src/authorization/authorization.ts +++ b/src/authorization/authorization.ts @@ -83,6 +83,18 @@ import { deserializeAuthorizationOrganizationMembership } from '../user-manageme export class Authorization { constructor(private readonly workos: WorkOS) {} + /** + * Create an environment role + * + * Create a new environment role. + * @param options - Object containing slug, name. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async createEnvironmentRole( options: CreateEnvironmentRoleOptions, ): Promise { @@ -93,6 +105,13 @@ export class Authorization { return deserializeEnvironmentRole(data); } + /** + * List environment roles + * + * List all environment roles in priority order. + * @returns {Promise} + * @throws 403 response from the API. + */ async listEnvironmentRoles(): Promise { const { data } = await this.workos.get( '/authorization/roles', @@ -103,6 +122,16 @@ export class Authorization { }; } + /** + * Get an environment role + * + * Get an environment role by its slug. + * @param slug - The slug of the environment role. + * @example "admin" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async getEnvironmentRole(slug: string): Promise { const { data } = await this.workos.get( `/authorization/roles/${slug}`, @@ -110,6 +139,19 @@ export class Authorization { return deserializeEnvironmentRole(data); } + /** + * Update an environment role + * + * Update an existing environment role. + * @param slug - The slug of the environment role. + * @example "admin" + * @param options - The request body. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async updateEnvironmentRole( slug: string, options: UpdateEnvironmentRoleOptions, @@ -121,6 +163,19 @@ export class Authorization { return deserializeEnvironmentRole(data); } + /** + * Set permissions for an environment role + * + * Replace all permissions on an environment role with the provided list. + * @param slug - The slug of the environment role. + * @example "admin" + * @param options - Object containing permissions. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async setEnvironmentRolePermissions( slug: string, options: SetEnvironmentRolePermissionsOptions, @@ -132,6 +187,19 @@ export class Authorization { return deserializeEnvironmentRole(data); } + /** + * Add a permission to an environment role + * + * Add a single permission to an environment role. If the permission is already assigned to the role, this operation has no effect. + * @param slug - The slug of the environment role. + * @example "admin" + * @param options - Object containing slug. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async addEnvironmentRolePermission( slug: string, options: AddEnvironmentRolePermissionOptions, @@ -143,6 +211,20 @@ export class Authorization { return deserializeEnvironmentRole(data); } + /** + * Create a custom role + * + * Create a new custom role for this organization. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param options - Object containing name. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async createOrganizationRole( organizationId: string, options: CreateOrganizationRoleOptions, @@ -154,6 +236,16 @@ export class Authorization { return deserializeOrganizationRole(data); } + /** + * List custom roles + * + * Get a list of all roles that apply to an organization. This includes both environment roles and custom roles, returned in priority order. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async listOrganizationRoles(organizationId: string): Promise { const { data } = await this.workos.get( `/authorization/organizations/${organizationId}/roles`, @@ -164,6 +256,18 @@ export class Authorization { }; } + /** + * Get a custom role + * + * Retrieve a role that applies to an organization by its slug. This can return either an environment role or a custom role. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param slug - The slug of the role. + * @example "org-billing-admin" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async getOrganizationRole( organizationId: string, slug: string, @@ -174,6 +278,21 @@ export class Authorization { return deserializeRole(data); } + /** + * Update a custom role + * + * Update an existing custom role. Only the fields provided in the request body will be updated. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param slug - The slug of the role. + * @example "org-billing-admin" + * @param options - The request body. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async updateOrganizationRole( organizationId: string, slug: string, @@ -186,6 +305,20 @@ export class Authorization { return deserializeOrganizationRole(data); } + /** + * Delete a custom role + * + * Delete an existing custom role. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param slug - The slug of the role. + * @example "org-admin" + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + */ async deleteOrganizationRole( organizationId: string, slug: string, @@ -195,6 +328,20 @@ export class Authorization { ); } + /** + * Set permissions for a custom role + * + * Replace all permissions on a custom role with the provided list. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param slug - The slug of the role. + * @example "org-admin" + * @param options - Object containing permissions. + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async updateRolePermissions( organizationId: string, slug: string, @@ -207,6 +354,21 @@ export class Authorization { return deserializeOrganizationRole(data); } + /** + * Add a permission to a custom role + * + * Add a single permission to a custom role. If the permission is already assigned to the role, this operation has no effect. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param slug - The slug of the role. + * @example "org-admin" + * @param options - Object containing slug. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async createRolePermission( organizationId: string, slug: string, @@ -219,6 +381,20 @@ export class Authorization { return deserializeOrganizationRole(data); } + /** + * Remove a permission from a custom role + * + * Remove a single permission from a custom role by its slug. + * @param organizationId - The ID of the organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param slug - The slug of the role. + * @example "org-admin" + * @param permissionSlug - The slug of the permission to remove. + * @example "documents:read" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async deleteRolePermission( organizationId: string, slug: string, @@ -229,6 +405,17 @@ export class Authorization { ); } + /** + * Create a permission + * + * Create a new permission in your WorkOS environment. The permission can then be assigned to environment roles and custom roles. + * @param options - Object containing slug, name. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async createPermission( options: CreatePermissionOptions, ): Promise { @@ -239,6 +426,14 @@ export class Authorization { return deserializePermission(data); } + /** + * List permissions + * + * Get a list of all permissions in your WorkOS environment. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {NotFoundException} 404 + */ async listPermissions( options?: ListPermissionsOptions, ): Promise> { @@ -260,6 +455,15 @@ export class Authorization { ); } + /** + * Get a permission + * + * Retrieve a permission by its unique slug. + * @param slug - A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. + * @example "documents:read" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getPermission(slug: string): Promise { const { data } = await this.workos.get( `/authorization/permissions/${slug}`, @@ -267,6 +471,18 @@ export class Authorization { return deserializePermission(data); } + /** + * Update a permission + * + * Update an existing permission. Only the fields provided in the request body will be updated. + * @param slug - A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. + * @example "documents:read" + * @param options - The request body. + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async updatePermission( slug: string, options: UpdatePermissionOptions, @@ -278,10 +494,31 @@ export class Authorization { return deserializePermission(data); } + /** + * Delete a permission + * + * Delete an existing permission. System permissions cannot be deleted. + * @param slug - A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. + * @example "documents:read" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async deletePermission(slug: string): Promise { await this.workos.delete(`/authorization/permissions/${slug}`); } + /** + * Get a resource + * + * Retrieve the details of an authorization resource by its ID. + * @param resourceId - The ID of the authorization resource. + * @example "authz_resource_01HXYZ123456789ABCDEFGHIJ" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async getResource(resourceId: string): Promise { const { data } = await this.workos.get( `/authorization/resources/${resourceId}`, @@ -289,6 +526,18 @@ export class Authorization { return deserializeAuthorizationResource(data); } + /** + * Create an authorization resource + * + * Create a new authorization resource. + * @param options - Object containing externalId, name, resourceTypeSlug, organizationId. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async createResource( options: CreateAuthorizationResourceOptions, ): Promise { @@ -299,6 +548,18 @@ export class Authorization { return deserializeAuthorizationResource(data); } + /** + * Update a resource + * + * Update an existing authorization resource. + * @param options - The request body. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async updateResource( options: UpdateAuthorizationResourceOptions, ): Promise { @@ -309,6 +570,20 @@ export class Authorization { return deserializeAuthorizationResource(data); } + /** + * Delete an authorization resource + * + * Delete an authorization resource and all its descendants. + * @param options.cascadeDelete - If true, deletes all descendant resources and role assignments. If not set and the resource has children or assignments, the request will fail. + * @default false + * @example false + * @param options - Additional query options. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + */ async deleteResource( options: DeleteAuthorizationResourceOptions, ): Promise { @@ -322,6 +597,15 @@ export class Authorization { await this.workos.delete(`/authorization/resources/${resourceId}`, query); } + /** + * List resources + * + * Get a paginated list of authorization resources. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {UnprocessableEntityException} 422 + */ async listResources( options: ListAuthorizationResourcesOptions = {}, ): Promise> { @@ -351,6 +635,20 @@ export class Authorization { ); } + /** + * Get a resource by external ID + * + * Retrieve the details of an authorization resource by its external ID, organization, and resource type. This is useful when you only have the external ID from your system and need to fetch the full resource details. + * @param organizationId - The ID of the organization that owns the resource. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param resourceTypeSlug - The slug of the resource type. + * @example "project" + * @param externalId - An identifier you provide to reference the resource in your system. + * @example "proj-456" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async getOrganizationResource( options: GetAuthorizationResourceByExternalIdOptions, ): Promise { @@ -361,6 +659,24 @@ export class Authorization { return deserializeAuthorizationResource(data); } + /** + * Update a resource by external ID + * + * Update an existing authorization resource using its external ID. + * @param organizationId - The ID of the organization that owns the resource. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param resourceTypeSlug - The slug of the resource type. + * @example "project" + * @param externalId - An identifier you provide to reference the resource in your system. + * @example "proj-456" + * @param options - The request body. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async updateOrganizationResource( options: UpdateAuthorizationResourceByExternalIdOptions, ): Promise { @@ -371,6 +687,23 @@ export class Authorization { ); return deserializeAuthorizationResource(data); } + /** + * Delete an authorization resource by external ID + * + * Delete an authorization resource by organization, resource type, and external ID. This also deletes all descendant resources. + * @param organizationId - The ID of the organization that owns the resource. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param resourceTypeSlug - The slug of the resource type. + * @example "project" + * @param externalId - An identifier you provide to reference the resource in your system. + * @example "proj-456" + * @param options - Additional query options. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + */ async deleteOrganizationResource( options: DeleteAuthorizationResourceByExternalIdOptions, ): Promise { @@ -388,6 +721,16 @@ export class Authorization { ); } + /** + * Check authorization + * + * Check if an organization membership has a specific permission on a resource. Supports identification by resource_id OR by resource_external_id + resource_type_slug. + * @param options - Object containing permissionSlug. + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async check( options: AuthorizationCheckOptions, ): Promise { @@ -398,6 +741,17 @@ export class Authorization { return data; } + /** + * List role assignments + * + * List all role assignments for an organization membership. This returns all roles that have been assigned to the user on resources, including organization-level and sub-resource roles. + * @param organizationMembershipId - The ID of the organization membership. + * @example "om_01HXYZ123456789ABCDEFGHIJ" + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async listOrganizationMembershipRoleAssignments( options: ListRoleAssignmentsOptions, ): Promise> { @@ -421,6 +775,16 @@ export class Authorization { ); } + /** + * Assign a role + * + * Assign a role to an organization membership on a specific resource. + * @param options - Object containing roleSlug. + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async assignRole(options: AssignRoleOptions): Promise { const { data } = await this.workos.post( `/authorization/organization_memberships/${options.organizationMembershipId}/role_assignments`, @@ -429,6 +793,16 @@ export class Authorization { return deserializeRoleAssignment(data); } + /** + * Remove a role assignment + * + * Remove a role assignment by role slug and resource. + * @param options - Object containing roleSlug. + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async removeRole(options: RemoveRoleOptions): Promise { await this.workos.deleteWithBody( `/authorization/organization_memberships/${options.organizationMembershipId}/role_assignments`, @@ -436,6 +810,18 @@ export class Authorization { ); } + /** + * Remove a role assignment by ID + * + * Remove a role assignment using its ID. + * @param organizationMembershipId - The ID of the organization membership. + * @example "om_01HXYZ123456789ABCDEFGHIJ" + * @param roleAssignmentId - The ID of the role assignment to remove. + * @example "role_assignment_01HXYZ123456789ABCDEFGH" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async deleteOrganizationMembershipRoleAssignment( options: RemoveRoleAssignmentOptions, ): Promise { @@ -444,6 +830,21 @@ export class Authorization { ); } + /** + * List resources for organization membership + * + * Returns all child resources of a parent resource where the organization membership has a specific permission. This is useful for resource discovery—answering "What projects can this user access in this workspace?" + * + * You must provide either `parent_resource_id` or both `parent_resource_external_id` and `parent_resource_type_slug` to identify the parent resource. + * @param organizationMembershipId - The ID of the organization membership. + * @example "om_01HXYZ123456789ABCDEFGHIJ" + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listOrganizationMembershipResources( options: ListResourcesForMembershipOptions, ): Promise> { @@ -470,6 +871,17 @@ export class Authorization { ); } + /** + * List organization memberships for resource + * + * Returns all organization memberships that have a specific permission on a resource instance. This is useful for answering "Who can access this resource?". + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listMembershipsForResource( options: ListMembershipsForResourceOptions, ): Promise> { @@ -501,6 +913,23 @@ export class Authorization { ); } + /** + * List memberships for a resource by external ID + * + * Returns all organization memberships that have a specific permission on a resource, using the resource's external ID. This is useful for answering "Who can access this resource?" when you only have the external ID. + * @param organizationId - The ID of the organization that owns the resource. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param resourceTypeSlug - The slug of the resource type this resource belongs to. + * @example "project" + * @param externalId - An identifier you provide to reference the resource in your system. + * @example "proj-456" + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listResourceOrganizationMemberships( options: ListMembershipsForResourceByExternalIdOptions, ): Promise> { @@ -532,6 +961,20 @@ export class Authorization { ); } + /** + * List effective permissions for an organization membership on a resource + * + * Returns all permissions the organization membership effectively has on a resource, including permissions inherited through roles assigned to ancestor resources. + * @param organizationMembershipId - The ID of the organization membership. + * @example "om_01HXYZ123456789ABCDEFGHIJ" + * @param resourceId - The ID of the authorization resource. + * @example "authz_resource_01HXYZ123456789ABCDEFGHIJ" + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listResourcePermissions( options: ListEffectivePermissionsOptions, ): Promise> { @@ -556,6 +999,16 @@ export class Authorization { ); } + /** + * List effective permissions for an organization membership on a resource by external ID + * + * Returns all permissions the organization membership effectively has on a resource identified by its external ID, including permissions inherited through roles assigned to ancestor resources. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listEffectivePermissionsByExternalId( options: ListEffectivePermissionsByExternalIdOptions, ): Promise> { diff --git a/src/authorization/interfaces/authorization-resource.interface.ts b/src/authorization/interfaces/authorization-resource.interface.ts index 9af08050a..fd8ef0497 100644 --- a/src/authorization/interfaces/authorization-resource.interface.ts +++ b/src/authorization/interfaces/authorization-resource.interface.ts @@ -1,13 +1,23 @@ export interface AuthorizationResource { + /** Distinguishes the Resource object. */ object: 'authorization_resource'; + /** The unique ID of the Resource. */ id: string; + /** An identifier you provide to reference the resource in your system. */ externalId: string; + /** A human-readable name for the Resource. */ name: string; + /** An optional description of the Resource. */ description: string | null; + /** The slug of the resource type this resource belongs to. */ resourceTypeSlug: string; + /** The ID of the organization that owns the resource. */ organizationId: string; + /** The ID of the parent resource, if this resource is nested. */ parentResourceId: string | null; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/authorization/interfaces/list-memberships-for-resource-options.interface.ts b/src/authorization/interfaces/list-memberships-for-resource-options.interface.ts index 4149becfc..079923726 100644 --- a/src/authorization/interfaces/list-memberships-for-resource-options.interface.ts +++ b/src/authorization/interfaces/list-memberships-for-resource-options.interface.ts @@ -2,6 +2,8 @@ import { PaginationOptions } from '../../common/interfaces/pagination-options.in export interface ListMembershipsForResourceOptions extends PaginationOptions { resourceId: string; + /** The permission slug to filter by. Only users with this permission on the resource are returned. */ permissionSlug: string; + /** Filter by assignment type. Use `direct` for direct assignments only, or `indirect` to include inherited assignments. */ assignment?: 'direct' | 'indirect'; } diff --git a/src/authorization/interfaces/role-assignment.interface.ts b/src/authorization/interfaces/role-assignment.interface.ts index 1589b6813..99f9baec4 100644 --- a/src/authorization/interfaces/role-assignment.interface.ts +++ b/src/authorization/interfaces/role-assignment.interface.ts @@ -15,11 +15,17 @@ export interface RoleAssignmentResourceResponse { } export interface RoleAssignment { + /** Distinguishes the role assignment object. */ object: 'role_assignment'; + /** Unique identifier of the role assignment. */ id: string; + /** The role included in the assignment. */ role: RoleAssignmentRole; + /** The resource to which the role is assigned. */ resource: RoleAssignmentResource; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/directory-sync/directory-sync.ts b/src/directory-sync/directory-sync.ts index fe3110fe7..e7b3723ee 100644 --- a/src/directory-sync/directory-sync.ts +++ b/src/directory-sync/directory-sync.ts @@ -24,6 +24,15 @@ import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize'; export class DirectorySync { constructor(private readonly workos: WorkOS) {} + /** + * List Directories + * + * Get a list of all of your existing directories matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {UnprocessableEntityException} 422 + */ async listDirectories( options?: ListDirectoriesOptions, ): Promise> { @@ -45,6 +54,16 @@ export class DirectorySync { ); } + /** + * Get a Directory + * + * Get the details of an existing directory. + * @param id - Unique identifier for the Directory. + * @example "directory_01ECAZ4NV9QMV47GW873HDCX74" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async getDirectory(id: string): Promise { const { data } = await this.workos.get( `/directories/${id}`, @@ -53,10 +72,29 @@ export class DirectorySync { return deserializeDirectory(data); } + /** + * Delete a Directory + * + * Permanently deletes an existing directory. It cannot be undone. + * @param id - Unique identifier for the Directory. + * @example "directory_01ECAZ4NV9QMV47GW873HDCX74" + * @returns {Promise} + * @throws 403 response from the API. + */ async deleteDirectory(id: string) { await this.workos.delete(`/directories/${id}`); } + /** + * List Directory Groups + * + * Get a list of all of existing directory groups matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listGroups( options: ListDirectoryGroupsOptions, ): Promise> { @@ -78,6 +116,17 @@ export class DirectorySync { ); } + /** + * List Directory Users + * + * Get a list of all of existing Directory Users matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise, ListDirectoryUsersOptions>>} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + * @throws {RateLimitExceededException} 429 + */ async listUsers( options: ListDirectoryUsersOptions, ): Promise< @@ -110,6 +159,14 @@ export class DirectorySync { ); } + /** + * Get a Directory User + * + * Get the details of an existing Directory User. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async getUser( user: string, ): Promise> { @@ -120,6 +177,14 @@ export class DirectorySync { return deserializeDirectoryUserWithGroups(data); } + /** + * Get a Directory Group + * + * Get the details of an existing Directory Group. + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async getGroup(group: string): Promise { const { data } = await this.workos.get( `/directory_groups/${group}`, diff --git a/src/directory-sync/interfaces/directory.interface.ts b/src/directory-sync/interfaces/directory.interface.ts index 19f450bb3..30a946fc3 100644 --- a/src/directory-sync/interfaces/directory.interface.ts +++ b/src/directory-sync/interfaces/directory.interface.ts @@ -34,15 +34,25 @@ export type DirectoryStateResponse = | 'validating'; export interface Directory { + /** Distinguishes the Directory object. */ object: 'directory'; + /** Unique identifier for the Directory. */ id: string; + /** The URL associated with an Enterprise Client. */ domain: string; + /** External Key for the Directory. */ externalKey: string; + /** The name of the directory. */ name: string; + /** The unique identifier for the Organization in which the directory resides. */ organizationId?: string; + /** Describes whether the Directory has been successfully connected to an external provider. */ state: DirectoryState; + /** The type of external Directory Provider integrated with. */ type: DirectoryType; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/directory-sync/interfaces/list-directories-options.interface.ts b/src/directory-sync/interfaces/list-directories-options.interface.ts index 57817af4b..daca5aadb 100644 --- a/src/directory-sync/interfaces/list-directories-options.interface.ts +++ b/src/directory-sync/interfaces/list-directories-options.interface.ts @@ -1,7 +1,9 @@ import { PaginationOptions } from '../../common/interfaces/pagination-options.interface'; export interface ListDirectoriesOptions extends PaginationOptions { + /** Filter Directories by their associated organization. */ organizationId?: string; + /** Searchable text to match against Directory names. */ search?: string; } diff --git a/src/events/events.ts b/src/events/events.ts index 22228efcd..705db2eac 100644 --- a/src/events/events.ts +++ b/src/events/events.ts @@ -7,6 +7,15 @@ import { Event, EventResponse, List, ListResponse } from '../common/interfaces'; export class Events { constructor(private readonly workos: WorkOS) {} + /** + * List events + * + * List events for the current environment. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {BadRequestException} 400 + * @throws {UnprocessableEntityException} 422 + */ async listEvents(options: ListEventOptions): Promise> { const { data } = await this.workos.get>( `/events`, diff --git a/src/feature-flags/feature-flags.ts b/src/feature-flags/feature-flags.ts index fb67c17d1..fca1fd324 100644 --- a/src/feature-flags/feature-flags.ts +++ b/src/feature-flags/feature-flags.ts @@ -17,6 +17,16 @@ import { ListUserFeatureFlagsOptions } from '../user-management/interfaces/list- export class FeatureFlags { constructor(private readonly workos: WorkOS) {} + /** + * List feature flags + * + * Get a list of all of your existing feature flags matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listFeatureFlags( options?: ListFeatureFlagsOptions, ): Promise> { @@ -38,6 +48,15 @@ export class FeatureFlags { ); } + /** + * Get a feature flag + * + * Get the details of an existing feature flag by its slug. + * @param slug - A unique key to reference the Feature Flag. + * @example "advanced-analytics" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getFeatureFlag(slug: string): Promise { const { data } = await this.workos.get( `/feature-flags/${slug}`, @@ -46,6 +65,15 @@ export class FeatureFlags { return deserializeFeatureFlag(data); } + /** + * Enable a feature flag + * + * Enables a feature flag in the current environment. + * @param slug - A unique key to reference the Feature Flag. + * @example "advanced-analytics" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async enableFeatureFlag(slug: string): Promise { const { data } = await this.workos.put( `/feature-flags/${slug}/enable`, @@ -55,6 +83,15 @@ export class FeatureFlags { return deserializeFeatureFlag(data); } + /** + * Disable a feature flag + * + * Disables a feature flag in the current environment. + * @param slug - A unique key to reference the Feature Flag. + * @example "advanced-analytics" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async disableFeatureFlag(slug: string): Promise { const { data } = await this.workos.put( `/feature-flags/${slug}/disable`, @@ -64,16 +101,44 @@ export class FeatureFlags { return deserializeFeatureFlag(data); } + /** + * Add a feature flag target + * + * Enables a feature flag for a specific target in the current environment. Currently, supported targets include users and organizations. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async addFlagTarget(options: AddFlagTargetOptions): Promise { const { slug, targetId } = options; await this.workos.post(`/feature-flags/${slug}/targets/${targetId}`, {}); } + /** + * Remove a feature flag target + * + * Removes a target from the feature flag's target list in the current environment. Currently, supported targets include users and organizations. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async removeFlagTarget(options: RemoveFlagTargetOptions): Promise { const { slug, targetId } = options; await this.workos.delete(`/feature-flags/${slug}/targets/${targetId}`); } + /** + * List enabled feature flags for an organization + * + * Get a list of all enabled feature flags for an organization. + * @param organizationId - Unique identifier of the Organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {NotFoundException} 404 + */ async listOrganizationFeatureFlags( options: ListOrganizationFeatureFlagsOptions, ): Promise> { @@ -97,6 +162,16 @@ export class FeatureFlags { ); } + /** + * List enabled feature flags for a user + * + * Get a list of all enabled feature flags for the provided user. This includes feature flags enabled specifically for the user as well as any organizations that the user is a member of. + * @param userId - The ID of the user. + * @example "user_01E4ZCR3C56J083X43JQXF3JK5" + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {NotFoundException} 404 + */ async listUserFeatureFlags( options: ListUserFeatureFlagsOptions, ): Promise> { diff --git a/src/feature-flags/interfaces/feature-flag.interface.ts b/src/feature-flags/interfaces/feature-flag.interface.ts index d8430dcc5..a8784453c 100644 --- a/src/feature-flags/interfaces/feature-flag.interface.ts +++ b/src/feature-flags/interfaces/feature-flag.interface.ts @@ -1,13 +1,23 @@ export interface FeatureFlag { + /** Distinguishes the Feature Flag object. */ object: 'feature_flag'; + /** Unique identifier of the Feature Flag. */ id: string; + /** A descriptive name for the Feature Flag. This field does not need to be unique. */ name: string; + /** A unique key to reference the Feature Flag. */ slug: string; + /** A description for the Feature Flag. */ description: string; + /** Labels assigned to the Feature Flag for categorizing and filtering. */ tags: string[]; + /** Specifies whether the Feature Flag is active for the current environment. */ enabled: boolean; + /** The value returned for users and organizations who don't match any configured targeting rules. */ defaultValue: boolean; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/multi-factor-auth/multi-factor-auth.ts b/src/multi-factor-auth/multi-factor-auth.ts index d6246787a..43bc02eb2 100644 --- a/src/multi-factor-auth/multi-factor-auth.ts +++ b/src/multi-factor-auth/multi-factor-auth.ts @@ -38,10 +38,28 @@ import { deserializeFactor as deserializeUMFactor } from '../user-management/ser export class MultiFactorAuth { constructor(private readonly workos: WorkOS) {} + /** + * Delete Factor + * + * Permanently deletes an Authentication Factor. It cannot be undone. + * @param id - The unique ID of the Factor. + * @example "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async deleteFactor(id: string) { await this.workos.delete(`/auth/factors/${id}`); } + /** + * Get Factor + * + * Gets an Authentication Factor. + * @param id - The unique ID of the Factor. + * @example "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getFactor(id: string): Promise { const { data } = await this.workos.get( `/auth/factors/${id}`, @@ -50,6 +68,14 @@ export class MultiFactorAuth { return deserializeFactor(data); } + /** + * Enroll Factor + * + * Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge. + * @param options - Object containing type. + * @returns {Promise} + * @throws {UnprocessableEntityException} 422 + */ async enrollFactor(options: EnrollFactorOptions): Promise { const { data } = await this.workos.post( '/auth/factors/enroll', @@ -76,6 +102,17 @@ export class MultiFactorAuth { return deserializeFactorWithSecrets(data); } + /** + * Challenge Factor + * + * Creates a Challenge for an Authentication Factor. + * @param id - The unique ID of the Authentication Factor to be challenged. + * @example "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * @param options - The request body. + * @returns {Promise} + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async challengeFactor(options: ChallengeFactorOptions): Promise { const { data } = await this.workos.post( `/auth/factors/${options.authenticationFactorId}/challenge`, @@ -88,6 +125,18 @@ export class MultiFactorAuth { return deserializeChallenge(data); } + /** + * Verify Challenge + * + * Verifies an Authentication Challenge. + * @param id - The unique ID of the Authentication Challenge. + * @example "auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * @param options - Object containing code. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async verifyChallenge( options: VerifyChallengeOptions, ): Promise { @@ -101,6 +150,14 @@ export class MultiFactorAuth { return deserializeVerifyResponse(data); } + /** + * Enroll an authentication factor + * + * Enrolls a user in a new [authentication factor](https://workos.com/docs/reference/authkit/mfa/authentication-factor). + * @param payload - Object containing type. + * @returns {Promise} + * @throws {UnprocessableEntityException} 422 + */ async createUserAuthFactor(payload: EnrollAuthFactorOptions): Promise<{ authenticationFactor: UMFactorWithSecrets; authenticationChallenge: Challenge; @@ -123,6 +180,14 @@ export class MultiFactorAuth { }; } + /** + * List authentication factors + * + * Lists the [authentication factors](https://workos.com/docs/reference/authkit/mfa/authentication-factor) for a user. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {UnprocessableEntityException} 422 + */ async listUserAuthFactors( options: ListAuthFactorsOptions, ): Promise> { diff --git a/src/organization-domains/interfaces/organization-domain.interface.ts b/src/organization-domains/interfaces/organization-domain.interface.ts index 62e8b2c43..1ac7d1d46 100644 --- a/src/organization-domains/interfaces/organization-domain.interface.ts +++ b/src/organization-domains/interfaces/organization-domain.interface.ts @@ -10,15 +10,25 @@ export enum OrganizationDomainVerificationStrategy { } export interface OrganizationDomain { + /** Distinguishes the organization domain object. */ object: 'organization_domain'; + /** Unique identifier of the organization domain. */ id: string; + /** Domain for the organization domain. */ domain: string; + /** ID of the parent Organization. */ organizationId: string; + /** Verification state of the domain. */ state: OrganizationDomainState; + /** Validation token to be used in DNS TXT record. */ verificationToken?: string; + /** Strategy used to verify the domain. */ verificationStrategy: OrganizationDomainVerificationStrategy; + /** The prefix used in DNS verification. */ verificationPrefix?: string; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/organization-domains/organization-domains.ts b/src/organization-domains/organization-domains.ts index 5eef17257..cd84b6ec3 100644 --- a/src/organization-domains/organization-domains.ts +++ b/src/organization-domains/organization-domains.ts @@ -10,6 +10,15 @@ import { deserializeOrganizationDomain } from './serializers/organization-domain export class OrganizationDomains { constructor(private readonly workos: WorkOS) {} + /** + * Get an Organization Domain + * + * Get the details of an existing organization domain. + * @param id - Unique identifier of the organization domain. + * @example "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getOrganizationDomain(id: string): Promise { const { data } = await this.workos.get( `/organization_domains/${id}`, @@ -18,6 +27,15 @@ export class OrganizationDomains { return deserializeOrganizationDomain(data); } + /** + * Verify an Organization Domain + * + * Initiates verification process for an Organization Domain. + * @param id - Unique identifier of the organization domain. + * @example "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * @returns {Promise} + * @throws {BadRequestException} 400 + */ async verifyOrganizationDomain(id: string): Promise { const { data } = await this.workos.post( `/organization_domains/${id}/verify`, @@ -27,6 +45,14 @@ export class OrganizationDomains { return deserializeOrganizationDomain(data); } + /** + * Create an Organization Domain + * + * Creates a new Organization Domain. + * @param payload - Object containing domain, organizationId. + * @returns {Promise} + * @throws {ConflictException} 409 + */ async createOrganizationDomain( payload: CreateOrganizationDomainOptions, ): Promise { @@ -38,6 +64,15 @@ export class OrganizationDomains { return deserializeOrganizationDomain(data); } + /** + * Delete an Organization Domain + * + * Permanently deletes an organization domain. It cannot be undone. + * @param id - Unique identifier of the organization domain. + * @example "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async deleteOrganizationDomain(id: string): Promise { await this.workos.delete(`/organization_domains/${id}`); } diff --git a/src/organizations/interfaces/list-organizations-options.interface.ts b/src/organizations/interfaces/list-organizations-options.interface.ts index 835a4975c..d5dfded3d 100644 --- a/src/organizations/interfaces/list-organizations-options.interface.ts +++ b/src/organizations/interfaces/list-organizations-options.interface.ts @@ -1,5 +1,6 @@ import { PaginationOptions } from '../../common/interfaces/pagination-options.interface'; export interface ListOrganizationsOptions extends PaginationOptions { + /** The domains of an Organization. Any Organization with a matching domain will be returned. */ domains?: string[]; } diff --git a/src/organizations/interfaces/organization.interface.ts b/src/organizations/interfaces/organization.interface.ts index 74e265472..53b32b793 100644 --- a/src/organizations/interfaces/organization.interface.ts +++ b/src/organizations/interfaces/organization.interface.ts @@ -4,15 +4,28 @@ import { } from '../../organization-domains/interfaces/organization-domain.interface'; export interface Organization { + /** Distinguishes the Organization object. */ object: 'organization'; + /** Unique identifier of the Organization. */ id: string; + /** A descriptive name for the Organization. This field does not need to be unique. */ name: string; + /** + * Whether the Organization allows profiles outside of its managed domains. + * @deprecated + */ allowProfilesOutsideOrganization: boolean; + /** List of Organization Domains. */ domains: OrganizationDomain[]; + /** The Stripe customer ID of the Organization. */ stripeCustomerId?: string; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; + /** The external ID of the Organization. */ externalId: string | null; + /** Object containing [metadata](https://workos.com/docs/authkit/metadata) key/value pairs associated with the Organization. */ metadata: Record; } diff --git a/src/organizations/organizations.ts b/src/organizations/organizations.ts index 2cae8fe43..87f18a2a9 100644 --- a/src/organizations/organizations.ts +++ b/src/organizations/organizations.ts @@ -19,6 +19,14 @@ import { fetchAndDeserialize } from '../common/utils/fetch-and-deserialize'; export class Organizations { constructor(private readonly workos: WorkOS) {} + /** + * List Organizations + * + * Get a list of all of your existing organizations matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {UnprocessableEntityException} 422 + */ async listOrganizations( options?: ListOrganizationsOptions, ): Promise> { @@ -40,6 +48,16 @@ export class Organizations { ); } + /** + * Create an Organization + * + * Creates a new organization in the current environment. + * @param payload - Object containing name. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async createOrganization( payload: CreateOrganizationOptions, requestOptions: CreateOrganizationRequestOptions = {}, @@ -53,10 +71,28 @@ export class Organizations { return deserializeOrganization(data); } + /** + * Delete an Organization + * + * Permanently deletes an organization in the current environment. It cannot be undone. + * @param id - Unique identifier of the Organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @returns {Promise} + * @throws 403 response from the API. + */ async deleteOrganization(id: string) { await this.workos.delete(`/organizations/${id}`); } + /** + * Get an Organization + * + * Get the details of an existing organization. + * @param id - Unique identifier of the Organization. + * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getOrganization(id: string): Promise { const { data } = await this.workos.get( `/organizations/${id}`, @@ -65,6 +101,15 @@ export class Organizations { return deserializeOrganization(data); } + /** + * Get an Organization by External ID + * + * Get the details of an existing organization by an [external identifier](https://workos.com/docs/authkit/metadata/external-identifiers). + * @param externalId - The external ID of the Organization. + * @example "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getOrganizationByExternalId(externalId: string): Promise { const { data } = await this.workos.get( `/organizations/external_id/${externalId}`, @@ -73,6 +118,18 @@ export class Organizations { return deserializeOrganization(data); } + /** + * Update an Organization + * + * Updates an organization in the current environment. + * @param payload - The request body. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {ConflictException} 409 + * @throws {UnprocessableEntityException} 422 + */ async updateOrganization( options: UpdateOrganizationOptions, ): Promise { diff --git a/src/sso/interfaces/connection.interface.ts b/src/sso/interfaces/connection.interface.ts index e70bec8a7..3cdf78c97 100644 --- a/src/sso/interfaces/connection.interface.ts +++ b/src/sso/interfaces/connection.interface.ts @@ -7,14 +7,22 @@ export interface ConnectionDomain { } export interface Connection { + /** Distinguishes the Connection object. */ object: 'connection'; + /** Unique identifier for the Connection. */ id: string; + /** Unique identifier for the Organization in which the Connection resides. */ organizationId?: string; + /** A human-readable name for the Connection. This will most commonly be the organization's name. */ name: string; + /** Indicates whether a Connection is able to authenticate users. */ state: 'draft' | 'active' | 'inactive' | 'validating'; + /** List of Organization Domains. */ domains: ConnectionDomain[]; type: ConnectionType; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/sso/interfaces/list-connections-options.interface.ts b/src/sso/interfaces/list-connections-options.interface.ts index 811521556..7059d38d3 100644 --- a/src/sso/interfaces/list-connections-options.interface.ts +++ b/src/sso/interfaces/list-connections-options.interface.ts @@ -2,8 +2,11 @@ import { PaginationOptions } from '../../common/interfaces/pagination-options.in import { ConnectionType } from './connection-type.enum'; export interface ListConnectionsOptions extends PaginationOptions { + /** Filter Connections by their type. */ connectionType?: ConnectionType; + /** Filter Connections by their associated domain. */ domain?: string; + /** Filter Connections by their associated organization. */ organizationId?: string; } diff --git a/src/sso/interfaces/profile.interface.ts b/src/sso/interfaces/profile.interface.ts index 850216e6a..6c59c79a9 100644 --- a/src/sso/interfaces/profile.interface.ts +++ b/src/sso/interfaces/profile.interface.ts @@ -3,18 +3,31 @@ import { RoleResponse } from '../../roles/interfaces'; import { ConnectionType } from './connection-type.enum'; export interface Profile { + /** Unique identifier of the profile. */ id: string; + /** The user's unique identifier from the identity provider. */ idpId: string; + /** The ID of the organization the user belongs to. */ organizationId?: string; + /** The ID of the SSO connection used for authentication. */ connectionId: string; + /** The type of SSO connection. */ connectionType: ConnectionType; + /** The user's email address. */ email: string; + /** The user's first name. */ firstName?: string; + /** The user's last name. */ lastName?: string; + /** The role assigned to the user within the organization, if applicable. */ role?: RoleResponse; + /** The roles assigned to the user within the organization, if applicable. */ roles?: RoleResponse[]; + /** The groups the user belongs to, as returned by the identity provider. */ groups?: string[]; + /** Custom attribute mappings defined for the connection, returned as key-value pairs. */ customAttributes?: CustomAttributesType; + /** The complete set of raw attributes returned by the identity provider. */ rawAttributes?: { [key: string]: any }; } diff --git a/src/sso/sso.ts b/src/sso/sso.ts index d66415309..e8b851944 100644 --- a/src/sso/sso.ts +++ b/src/sso/sso.ts @@ -27,6 +27,15 @@ import { export class SSO { constructor(private readonly workos: WorkOS) {} + /** + * List Connections + * + * Get a list of all of your existing connections matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws 403 response from the API. + * @throws {UnprocessableEntityException} 422 + */ async listConnections( options?: ListConnectionsOptions, ): Promise> { @@ -47,6 +56,16 @@ export class SSO { options ? serializeListConnectionsOptions(options) : undefined, ); } + /** + * Delete a Connection + * + * Permanently deletes an existing connection. It cannot be undone. + * @param id - Unique identifier for the Connection. + * @example "conn_01E4ZCR3C56J083X43JQXF3JK5" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async deleteConnection(id: string) { await this.workos.delete(`/connections/${id}`); } @@ -169,6 +188,16 @@ export class SSO { } // @oagen-ignore-end + /** + * Get a Connection + * + * Get the details of an existing connection. + * @param id - Unique identifier for the Connection. + * @example "conn_01E4ZCR3C56J083X43JQXF3JK5" + * @returns {Promise} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + */ async getConnection(id: string): Promise { const { data } = await this.workos.get( `/connections/${id}`, @@ -239,6 +268,14 @@ export class SSO { return deserializeProfileAndToken(data); } + /** + * Get a User Profile + * + * Exchange an access token for a user's [Profile](https://workos.com/docs/reference/sso/profile). Because this profile is returned in the [Get a Profile and Token endpoint](https://workos.com/docs/reference/sso/profile/get-profile-and-token) your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile. + * @returns {Promise>} + * @throws {UnauthorizedException} 401 + * @throws {NotFoundException} 404 + */ async getProfile({ accessToken, }: GetProfileOptions): Promise> { diff --git a/src/user-management/interfaces/email-verification.interface.ts b/src/user-management/interfaces/email-verification.interface.ts index 8af6cb8fb..0999e2102 100644 --- a/src/user-management/interfaces/email-verification.interface.ts +++ b/src/user-management/interfaces/email-verification.interface.ts @@ -1,11 +1,19 @@ export interface EmailVerification { + /** Distinguishes the email verification object. */ object: 'email_verification'; + /** The unique ID of the email verification code. */ id: string; + /** The unique ID of the user. */ userId: string; + /** The email address of the user. */ email: string; + /** The timestamp when the email verification code expires. */ expiresAt: string; + /** The code used to verify the email. */ code: string; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/user-management/interfaces/invitation.interface.ts b/src/user-management/interfaces/invitation.interface.ts index a485e6e40..605ec0f96 100644 --- a/src/user-management/interfaces/invitation.interface.ts +++ b/src/user-management/interfaces/invitation.interface.ts @@ -1,17 +1,31 @@ export interface Invitation { + /** Distinguishes the invitation object. */ object: 'invitation'; + /** The unique ID of the invitation. */ id: string; + /** The email address of the recipient. */ email: string; + /** The state of the invitation. */ state: 'pending' | 'accepted' | 'expired' | 'revoked'; + /** The timestamp when the invitation was accepted, or null if not yet accepted. */ acceptedAt: string | null; + /** The timestamp when the invitation was revoked, or null if not revoked. */ revokedAt: string | null; + /** The timestamp when the invitation expires. */ expiresAt: string; + /** The ID of the [organization](https://workos.com/docs/reference/organization) that the recipient will join. */ organizationId: string | null; + /** The ID of the user who invited the recipient, if provided. */ inviterUserId: string | null; + /** The ID of the user who accepted the invitation, once accepted. */ acceptedUserId: string | null; + /** The token used to accept the invitation. */ token: string; + /** The URL where the recipient can accept the invitation. */ acceptInvitationUrl: string; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/user-management/interfaces/list-invitations-options.interface.ts b/src/user-management/interfaces/list-invitations-options.interface.ts index 08b735f67..dca4cb035 100644 --- a/src/user-management/interfaces/list-invitations-options.interface.ts +++ b/src/user-management/interfaces/list-invitations-options.interface.ts @@ -1,7 +1,9 @@ import { PaginationOptions } from '../../common/interfaces'; export interface ListInvitationsOptions extends PaginationOptions { + /** The ID of the [organization](https://workos.com/docs/reference/organization) that the recipient will join. */ organizationId?: string; + /** The email address of the recipient. */ email?: string; } diff --git a/src/user-management/interfaces/list-users-options.interface.ts b/src/user-management/interfaces/list-users-options.interface.ts index 41be875ca..27ec34f66 100644 --- a/src/user-management/interfaces/list-users-options.interface.ts +++ b/src/user-management/interfaces/list-users-options.interface.ts @@ -1,7 +1,9 @@ import { PaginationOptions } from '../../common/interfaces/pagination-options.interface'; export interface ListUsersOptions extends PaginationOptions { + /** Filter users by their email address. */ email?: string; + /** Filter users by the organization they are a member of. */ organizationId?: string; } diff --git a/src/user-management/interfaces/magic-auth.interface.ts b/src/user-management/interfaces/magic-auth.interface.ts index 1fc599789..7d78cfd00 100644 --- a/src/user-management/interfaces/magic-auth.interface.ts +++ b/src/user-management/interfaces/magic-auth.interface.ts @@ -1,11 +1,19 @@ export interface MagicAuth { + /** Distinguishes the Magic Auth object. */ object: 'magic_auth'; + /** The unique ID of the Magic Auth code. */ id: string; + /** The unique ID of the user. */ userId: string; + /** The email address of the user. */ email: string; + /** The timestamp when the Magic Auth code expires. */ expiresAt: string; + /** The code used to verify the Magic Auth code. */ code: string; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; } diff --git a/src/user-management/interfaces/organization-membership.interface.ts b/src/user-management/interfaces/organization-membership.interface.ts index 7e1ad39a5..9d8b3cf49 100644 --- a/src/user-management/interfaces/organization-membership.interface.ts +++ b/src/user-management/interfaces/organization-membership.interface.ts @@ -15,7 +15,9 @@ export interface BaseOrganizationMembership { } export interface OrganizationMembership extends BaseOrganizationMembership { + /** The name of the organization which the user belongs to. */ organizationName: string; + /** The primary role assigned to the user within the organization. */ role: RoleResponse; roles?: RoleResponse[]; } diff --git a/src/user-management/interfaces/password-reset.interface.ts b/src/user-management/interfaces/password-reset.interface.ts index 1d9644394..387b77d83 100644 --- a/src/user-management/interfaces/password-reset.interface.ts +++ b/src/user-management/interfaces/password-reset.interface.ts @@ -1,11 +1,19 @@ export interface PasswordReset { + /** Distinguishes the password reset object. */ object: 'password_reset'; + /** The unique ID of the password reset object. */ id: string; + /** The unique ID of the user. */ userId: string; + /** The email address of the user. */ email: string; + /** The token used to reset the password. */ passwordResetToken: string; + /** The URL where the user can reset their password. */ passwordResetUrl: string; + /** The timestamp when the password reset token expires. */ expiresAt: string; + /** The timestamp when the password reset token was created. */ createdAt: string; } diff --git a/src/user-management/interfaces/user.interface.ts b/src/user-management/interfaces/user.interface.ts index 31e68ce66..b22bd93a0 100644 --- a/src/user-management/interfaces/user.interface.ts +++ b/src/user-management/interfaces/user.interface.ts @@ -1,16 +1,30 @@ +/** The user object. */ export interface User { + /** Distinguishes the user object. */ object: 'user'; + /** The unique ID of the user. */ id: string; + /** The email address of the user. */ email: string; + /** Whether the user's email has been verified. */ emailVerified: boolean; + /** A URL reference to an image representing the user. */ profilePictureUrl: string | null; + /** The first name of the user. */ firstName: string | null; + /** The last name of the user. */ lastName: string | null; + /** The timestamp when the user last signed in. */ lastSignInAt: string | null; + /** The user's preferred locale. */ locale: string | null; + /** An ISO 8601 timestamp. */ createdAt: string; + /** An ISO 8601 timestamp. */ updatedAt: string; + /** The external ID of the user. */ externalId: string | null; + /** Object containing metadata key/value pairs associated with the user. */ metadata: Record; } diff --git a/src/user-management/user-management.ts b/src/user-management/user-management.ts index cff94a5ce..cd9f8a346 100644 --- a/src/user-management/user-management.ts +++ b/src/user-management/user-management.ts @@ -210,6 +210,13 @@ export class UserManagement { } // @oagen-ignore-end + /** + * Get a user + * + * Get the details of an existing user. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getUser(userId: string): Promise { const { data } = await this.workos.get( `/user_management/users/${userId}`, @@ -218,6 +225,15 @@ export class UserManagement { return deserializeUser(data); } + /** + * Get a user by external ID + * + * Get the details of an existing user by an [external identifier](https://workos.com/docs/authkit/metadata/external-identifiers). + * @param externalId - The external ID of the user. + * @example "f1ffa2b2-c20b-4d39-be5c-212726e11222" + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getUserByExternalId(externalId: string): Promise { const { data } = await this.workos.get( `/user_management/users/external_id/${externalId}`, @@ -226,6 +242,14 @@ export class UserManagement { return deserializeUser(data); } + /** + * List users + * + * Get a list of all of your existing users matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {UnprocessableEntityException} 422 + */ async listUsers( options?: ListUsersOptions, ): Promise> { @@ -247,6 +271,16 @@ export class UserManagement { ); } + /** + * Create a user + * + * Create a new user in the current environment. + * @param payload - Object containing email. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async createUser(payload: CreateUserOptions): Promise { const { data } = await this.workos.post< UserResponse, @@ -256,6 +290,7 @@ export class UserManagement { return deserializeUser(data); } + /** Authenticate with magic auth. */ async authenticateWithMagicAuth( payload: AuthenticateWithMagicAuthOptions, ): Promise { @@ -280,6 +315,7 @@ export class UserManagement { }); } + /** Authenticate with password. */ async authenticateWithPassword( payload: AuthenticateWithPasswordOptions, ): Promise { @@ -433,6 +469,7 @@ export class UserManagement { }); } + /** Authenticate with totp. */ async authenticateWithTotp( payload: AuthenticateWithTotpOptions, ): Promise { @@ -457,6 +494,7 @@ export class UserManagement { }); } + /** Authenticate with email verification. */ async authenticateWithEmailVerification( payload: AuthenticateWithEmailVerificationOptions, ): Promise { @@ -481,6 +519,7 @@ export class UserManagement { }); } + /** Authenticate with organization selection. */ async authenticateWithOrganizationSelection( payload: AuthenticateWithOrganizationSelectionOptions, ): Promise { @@ -679,6 +718,13 @@ export class UserManagement { } // @oagen-ignore-end + /** + * Get an email verification code + * + * Get the details of an existing email verification code that can be used to send an email to a user for verification. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getEmailVerification( emailVerificationId: string, ): Promise { @@ -689,6 +735,15 @@ export class UserManagement { return deserializeEmailVerification(data); } + /** + * Send verification email + * + * Sends an email that contains a one-time code used to verify a user’s email address. + * @returns {Promise<{ user: User; }>} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {RateLimitExceededException} 429 + */ async sendVerificationEmail({ userId, }: SendVerificationEmailOptions): Promise<{ user: User }> { @@ -700,6 +755,13 @@ export class UserManagement { return { user: deserializeUser(data.user) }; } + /** + * Get Magic Auth code details + * + * Get the details of an existing [Magic Auth](https://workos.com/docs/reference/authkit/magic-auth) code that can be used to send an email to a user for authentication. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getMagicAuth(magicAuthId: string): Promise { const { data } = await this.workos.get( `/user_management/magic_auth/${magicAuthId}`, @@ -708,6 +770,16 @@ export class UserManagement { return deserializeMagicAuth(data); } + /** + * Create a Magic Auth code + * + * Creates a one-time authentication code that can be sent to the user's email address. The code expires in 10 minutes. To verify the code, [authenticate the user with Magic Auth](https://workos.com/docs/reference/authkit/authentication/magic-auth). + * @param options - Object containing email. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {UnprocessableEntityException} 422 + * @throws {RateLimitExceededException} 429 + */ async createMagicAuth(options: CreateMagicAuthOptions): Promise { const { data } = await this.workos.post< MagicAuthResponse, @@ -722,6 +794,16 @@ export class UserManagement { return deserializeMagicAuth(data); } + /** + * Verify email + * + * Verifies an email address using the one-time code received by the user. + * @param options - Object containing code. + * @returns {Promise<{ user: User; }>} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async verifyEmail({ code, userId, @@ -736,6 +818,13 @@ export class UserManagement { return { user: deserializeUser(data.user) }; } + /** + * Get a password reset token + * + * Get the details of an existing password reset token that can be used to reset a user's password. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getPasswordReset(passwordResetId: string): Promise { const { data } = await this.workos.get( `/user_management/password_reset/${passwordResetId}`, @@ -760,6 +849,17 @@ export class UserManagement { return deserializePasswordReset(data); } + /** + * Create a password reset token + * + * Creates a one-time token that can be used to reset a user's password. + * @param payload - Object containing email. + * @returns {Promise<{ user: User; }>} + * @throws 403 response from the API. + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + * @throws {RateLimitExceededException} 429 + */ async resetPassword(payload: ResetPasswordOptions): Promise<{ user: User }> { const { data } = await this.workos.post< { user: UserResponse }, @@ -772,6 +872,15 @@ export class UserManagement { return { user: deserializeUser(data.user) }; } + /** + * Update a user + * + * Updates properties of a user. The omitted properties will be left unchanged. + * @param payload - The request body. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {UnprocessableEntityException} 422 + */ async updateUser(payload: UpdateUserOptions): Promise { const { data } = await this.workos.put( `/user_management/users/${payload.userId}`, @@ -781,6 +890,15 @@ export class UserManagement { return deserializeUser(data); } + /** + * List sessions + * + * Get a list of all active sessions for a specific user. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listSessions( userId: string, options?: ListSessionsOptions, @@ -803,10 +921,24 @@ export class UserManagement { ); } + /** + * Delete a user + * + * Permanently deletes a user in the current environment. It cannot be undone. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async deleteUser(userId: string) { await this.workos.delete(`/user_management/users/${userId}`); } + /** + * Get user identities + * + * Get a list of identities associated with the user. A user can have multiple associated identities after going through [identity linking](https://workos.com/docs/authkit/identity-linking). Currently only OAuth identities are supported. More provider types may be added in the future. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getUserIdentities(userId: string): Promise { if (!userId) { throw new TypeError(`Incomplete arguments. Need to specify 'userId'.`); @@ -819,6 +951,13 @@ export class UserManagement { return deserializeIdentities(data); } + /** + * Get an organization membership + * + * Get the details of an existing organization membership. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async getOrganizationMembership( organizationMembershipId: string, ): Promise { @@ -829,6 +968,16 @@ export class UserManagement { return deserializeOrganizationMembership(data); } + /** + * List organization memberships + * + * Get a list of all organization memberships matching the criteria specified. At least one of `user_id` or `organization_id` must be provided. By default only active memberships are returned. Use the `statuses` parameter to filter by other statuses. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async listOrganizationMemberships( options: ListOrganizationMembershipsOptions, ): Promise< @@ -864,6 +1013,18 @@ export class UserManagement { ); } + /** + * Create an organization membership + * + * Creates a new `active` organization membership for the given organization and user. + * + * Calling this API with an organization and user that match an `inactive` organization membership will activate the membership with the specified role(s). + * @param options - Object containing userId, organizationId. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async createOrganizationMembership( options: CreateOrganizationMembershipOptions, ): Promise { @@ -878,6 +1039,15 @@ export class UserManagement { return deserializeOrganizationMembership(data); } + /** + * Update an organization membership + * + * Update the details of an existing organization membership. + * @param options - The request body. + * @returns {Promise} + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async updateOrganizationMembership( organizationMembershipId: string, options: UpdateOrganizationMembershipOptions, @@ -893,6 +1063,13 @@ export class UserManagement { return deserializeOrganizationMembership(data); } + /** + * Delete an organization membership + * + * Permanently deletes an existing organization membership. It cannot be undone. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async deleteOrganizationMembership( organizationMembershipId: string, ): Promise { @@ -901,6 +1078,20 @@ export class UserManagement { ); } + /** + * Deactivate an organization membership + * + * Deactivates an `active` organization membership. Emits an [organization_membership.updated](https://workos.com/docs/events/organization-membership) event upon successful deactivation. + * + * - Deactivating an `inactive` membership is a no-op and does not emit an event. + * - Deactivating a `pending` membership returns an error. This membership should be [deleted](https://workos.com/docs/reference/authkit/organization-membership/delete) instead. + * + * See the [membership management documentation](https://workos.com/docs/authkit/users-organizations/organizations/membership-management) for additional details. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async deactivateOrganizationMembership( organizationMembershipId: string, ): Promise { @@ -912,6 +1103,20 @@ export class UserManagement { return deserializeOrganizationMembership(data); } + /** + * Reactivate an organization membership + * + * Reactivates an `inactive` organization membership, retaining the pre-existing role(s). Emits an [organization_membership.updated](https://workos.com/docs/events/organization-membership) event upon successful reactivation. + * + * - Reactivating an `active` membership is a no-op and does not emit an event. + * - Reactivating a `pending` membership returns an error. The user needs to [accept the invitation](https://workos.com/docs/authkit/invitations) instead. + * + * See the [membership management documentation](https://workos.com/docs/authkit/users-organizations/organizations/membership-management) for additional details. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async reactivateOrganizationMembership( organizationMembershipId: string, ): Promise { @@ -955,6 +1160,13 @@ export class UserManagement { return deserializeInvitation(data); } + /** + * Find an invitation by token + * + * Retrieve an existing invitation using the token. + * @returns {Promise} + * @throws {NotFoundException} 404 + */ async findInvitationByToken(invitationToken: string): Promise { const { data } = await this.workos.get( `/user_management/invitations/by_token/${invitationToken}`, @@ -963,6 +1175,14 @@ export class UserManagement { return deserializeInvitation(data); } + /** + * List invitations + * + * Get a list of all of invitations matching the criteria specified. + * @param options - Pagination and filter options. + * @returns {Promise>} + * @throws {UnprocessableEntityException} 422 + */ async listInvitations( options: ListInvitationsOptions, ): Promise> { @@ -984,6 +1204,16 @@ export class UserManagement { ); } + /** + * Send an invitation + * + * Sends an invitation email to the recipient. + * @param payload - Object containing email. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async sendInvitation(payload: SendInvitationOptions): Promise { const { data } = await this.workos.post< InvitationResponse, @@ -998,6 +1228,14 @@ export class UserManagement { return deserializeInvitation(data); } + /** + * Accept an invitation + * + * Accepts an invitation and, if linked to an organization, activates the user's membership in that organization. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + */ async acceptInvitation(invitationId: string): Promise { const { data } = await this.workos.post( `/user_management/invitations/${invitationId}/accept`, @@ -1007,6 +1245,13 @@ export class UserManagement { return deserializeInvitation(data); } + /** + * Revoke an invitation + * + * Revokes an existing invitation. + * @returns {Promise} + * @throws {BadRequestException} 400 + */ async revokeInvitation(invitationId: string): Promise { const { data } = await this.workos.post( `/user_management/invitations/${invitationId}/revoke`, @@ -1016,6 +1261,16 @@ export class UserManagement { return deserializeInvitation(data); } + /** + * Resend an invitation + * + * Resends an invitation email to the recipient. The invitation must be in a pending state. + * @param options - The request body. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async resendInvitation( invitationId: string, options?: ResendInvitationOptions, @@ -1031,6 +1286,14 @@ export class UserManagement { return deserializeInvitation(data); } + /** + * Revoke Session + * + * Revoke a [user session](https://workos.com/docs/reference/authkit/session). + * @param payload - Object containing sessionId. + * @returns {Promise} + * @throws {BadRequestException} 400 + */ async revokeSession(payload: RevokeSessionOptions): Promise { await this.workos.post( '/user_management/sessions/revoke', @@ -1191,6 +1454,18 @@ export class UserManagement { return { url, state, codeVerifier: pkce.codeVerifier }; } + /** + * Logout + * + * Logout a user from the current [session](https://workos.com/docs/reference/authkit/session). + * @param options.sessionId - The ID of the session to revoke. This can be extracted from the `sid` claim of the access token. + * @example "session_01H93ZY4F80QPBEZ1R5B2SHQG8" + * @param options.returnTo - The URL to redirect the user to after session revocation. + * @example "https://example.com" + * @param options - Additional query options. + * @returns {string} + * @throws {UnprocessableEntityException} 422 + */ getLogoutUrl(options: LogoutURLOptions): string { const { sessionId, returnTo } = options; diff --git a/src/widgets/widgets.ts b/src/widgets/widgets.ts index ed251d297..3de1f2601 100644 --- a/src/widgets/widgets.ts +++ b/src/widgets/widgets.ts @@ -11,6 +11,16 @@ import { export class Widgets { constructor(private readonly workos: WorkOS) {} + /** + * Generate a widget token + * + * Generate a widget token scoped to an organization and user with the specified scopes. + * @param payload - Object containing organizationId. + * @returns {Promise} + * @throws {BadRequestException} 400 + * @throws {NotFoundException} 404 + * @throws {UnprocessableEntityException} 422 + */ async createToken(payload: GetTokenOptions): Promise { const { data } = await this.workos.post< GetTokenResponseResponse, From 4d32a47264bc9cf3db6e38d73b21a30cedb64415 Mon Sep 17 00:00:00 2001 From: "Garen J. Torikian" Date: Tue, 21 Apr 2026 12:29:57 -0400 Subject: [PATCH 2/5] respond to bot feedback --- src/multi-factor-auth/multi-factor-auth.ts | 4 ---- src/user-management/user-management.ts | 10 ++++++---- src/widgets/widgets.ts | 2 +- 3 files changed, 7 insertions(+), 9 deletions(-) diff --git a/src/multi-factor-auth/multi-factor-auth.ts b/src/multi-factor-auth/multi-factor-auth.ts index 43bc02eb2..9166f9492 100644 --- a/src/multi-factor-auth/multi-factor-auth.ts +++ b/src/multi-factor-auth/multi-factor-auth.ts @@ -106,8 +106,6 @@ export class MultiFactorAuth { * Challenge Factor * * Creates a Challenge for an Authentication Factor. - * @param id - The unique ID of the Authentication Factor to be challenged. - * @example "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" * @param options - The request body. * @returns {Promise} * @throws {NotFoundException} 404 @@ -129,8 +127,6 @@ export class MultiFactorAuth { * Verify Challenge * * Verifies an Authentication Challenge. - * @param id - The unique ID of the Authentication Challenge. - * @example "auth_challenge_01FVYZ5QM8N98T9ME5BCB2BBMJ" * @param options - Object containing code. * @returns {Promise} * @throws {BadRequestException} 400 diff --git a/src/user-management/user-management.ts b/src/user-management/user-management.ts index cd9f8a346..792060ed4 100644 --- a/src/user-management/user-management.ts +++ b/src/user-management/user-management.ts @@ -214,6 +214,7 @@ export class UserManagement { * Get a user * * Get the details of an existing user. + * @param userId - The unique ID of the user. * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -850,10 +851,12 @@ export class UserManagement { } /** - * Create a password reset token + * Reset the password * - * Creates a one-time token that can be used to reset a user's password. - * @param payload - Object containing email. + * Sets a new password using the `token` query parameter from the link that + * the user received. Successfully resetting the password will verify a + * user's email, if it hasn't been verified yet. + * @param payload - Object containing the reset token and new password. * @returns {Promise<{ user: User; }>} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -1462,7 +1465,6 @@ export class UserManagement { * @example "session_01H93ZY4F80QPBEZ1R5B2SHQG8" * @param options.returnTo - The URL to redirect the user to after session revocation. * @example "https://example.com" - * @param options - Additional query options. * @returns {string} * @throws {UnprocessableEntityException} 422 */ diff --git a/src/widgets/widgets.ts b/src/widgets/widgets.ts index 3de1f2601..066a25313 100644 --- a/src/widgets/widgets.ts +++ b/src/widgets/widgets.ts @@ -16,7 +16,7 @@ export class Widgets { * * Generate a widget token scoped to an organization and user with the specified scopes. * @param payload - Object containing organizationId. - * @returns {Promise} + * @returns {Promise} * @throws {BadRequestException} 400 * @throws {NotFoundException} 404 * @throws {UnprocessableEntityException} 422 From 666f38ed91eeb42ee22c28a685693287c17d2d08 Mon Sep 17 00:00:00 2001 From: "Garen J. Torikian" Date: Tue, 21 Apr 2026 12:40:18 -0400 Subject: [PATCH 3/5] bot corrections --- src/multi-factor-auth/multi-factor-auth.ts | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/multi-factor-auth/multi-factor-auth.ts b/src/multi-factor-auth/multi-factor-auth.ts index 9166f9492..4df15e265 100644 --- a/src/multi-factor-auth/multi-factor-auth.ts +++ b/src/multi-factor-auth/multi-factor-auth.ts @@ -57,7 +57,7 @@ export class MultiFactorAuth { * Gets an Authentication Factor. * @param id - The unique ID of the Factor. * @example "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" - * @returns {Promise} + * @returns {Promise} * @throws {NotFoundException} 404 */ async getFactor(id: string): Promise { @@ -73,7 +73,7 @@ export class MultiFactorAuth { * * Enrolls an Authentication Factor to be used as an additional factor of authentication. The returned ID should be used to create an authentication Challenge. * @param options - Object containing type. - * @returns {Promise} + * @returns {Promise} * @throws {UnprocessableEntityException} 422 */ async enrollFactor(options: EnrollFactorOptions): Promise { @@ -107,7 +107,7 @@ export class MultiFactorAuth { * * Creates a Challenge for an Authentication Factor. * @param options - The request body. - * @returns {Promise} + * @returns {Promise} * @throws {NotFoundException} 404 * @throws {UnprocessableEntityException} 422 */ @@ -128,7 +128,7 @@ export class MultiFactorAuth { * * Verifies an Authentication Challenge. * @param options - Object containing code. - * @returns {Promise} + * @returns {Promise} * @throws {BadRequestException} 400 * @throws {NotFoundException} 404 * @throws {UnprocessableEntityException} 422 @@ -151,7 +151,7 @@ export class MultiFactorAuth { * * Enrolls a user in a new [authentication factor](https://workos.com/docs/reference/authkit/mfa/authentication-factor). * @param payload - Object containing type. - * @returns {Promise} + * @returns {Promise<{authenticationFactor: UMFactorWithSecrets; authenticationChallenge: Challenge}>} * @throws {UnprocessableEntityException} 422 */ async createUserAuthFactor(payload: EnrollAuthFactorOptions): Promise<{ @@ -181,7 +181,7 @@ export class MultiFactorAuth { * * Lists the [authentication factors](https://workos.com/docs/reference/authkit/mfa/authentication-factor) for a user. * @param options - Pagination and filter options. - * @returns {Promise>} + * @returns {Promise>} * @throws {UnprocessableEntityException} 422 */ async listUserAuthFactors( From 1ff68b5911ee8d40ef3ecd3cedcbe495ea5ae99b Mon Sep 17 00:00:00 2001 From: "Garen J. Torikian" Date: Tue, 21 Apr 2026 12:48:53 -0400 Subject: [PATCH 4/5] TIL: @example is a block --- src/api-keys/api-keys.ts | 15 +- src/audit-logs/audit-logs.ts | 5 +- src/authorization/authorization.ts | 206 ++++++++++++++---- src/directory-sync/directory-sync.ts | 10 +- src/feature-flags/feature-flags.ts | 25 ++- src/multi-factor-auth/multi-factor-auth.ts | 10 +- .../organization-domains.ts | 15 +- src/organizations/organizations.ts | 15 +- src/sso/sso.ts | 10 +- src/user-management/user-management.ts | 15 +- 10 files changed, 260 insertions(+), 66 deletions(-) diff --git a/src/api-keys/api-keys.ts b/src/api-keys/api-keys.ts index 4c1f2cc5f..78b074996 100644 --- a/src/api-keys/api-keys.ts +++ b/src/api-keys/api-keys.ts @@ -52,7 +52,10 @@ export class ApiKeys { * * 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" + * + * @example + * "api_key_01EHZNVPK3SFK441A1RGBFSHRT" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -65,7 +68,10 @@ export class ApiKeys { * * Get a list of all API keys for an organization. * @param organizationId - Unique identifier of the Organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param options - Pagination and filter options. * @returns {Promise>} * @throws {NotFoundException} 404 @@ -98,7 +104,10 @@ export class ApiKeys { * * Create a new API key for an organization. * @param organizationId - Unique identifier of the Organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param options - Object containing name. * @returns {Promise} * @throws {NotFoundException} 404 diff --git a/src/audit-logs/audit-logs.ts b/src/audit-logs/audit-logs.ts index bc072edd0..28fb73947 100644 --- a/src/audit-logs/audit-logs.ts +++ b/src/audit-logs/audit-logs.ts @@ -87,7 +87,10 @@ export class AuditLogs { * * 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" + * + * @example + * "audit_log_export_01GBZK5MP7TD1YCFQHFR22180V" + * * @returns {Promise} * @throws {NotFoundException} 404 */ diff --git a/src/authorization/authorization.ts b/src/authorization/authorization.ts index 61c810d79..d95be2f4c 100644 --- a/src/authorization/authorization.ts +++ b/src/authorization/authorization.ts @@ -127,7 +127,10 @@ export class Authorization { * * Get an environment role by its slug. * @param slug - The slug of the environment role. - * @example "admin" + * + * @example + * "admin" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -144,7 +147,10 @@ export class Authorization { * * Update an existing environment role. * @param slug - The slug of the environment role. - * @example "admin" + * + * @example + * "admin" + * * @param options - The request body. * @returns {Promise} * @throws {BadRequestException} 400 @@ -168,7 +174,10 @@ export class Authorization { * * Replace all permissions on an environment role with the provided list. * @param slug - The slug of the environment role. - * @example "admin" + * + * @example + * "admin" + * * @param options - Object containing permissions. * @returns {Promise} * @throws {BadRequestException} 400 @@ -192,7 +201,10 @@ export class Authorization { * * Add a single permission to an environment role. If the permission is already assigned to the role, this operation has no effect. * @param slug - The slug of the environment role. - * @example "admin" + * + * @example + * "admin" + * * @param options - Object containing slug. * @returns {Promise} * @throws {BadRequestException} 400 @@ -216,7 +228,10 @@ export class Authorization { * * Create a new custom role for this organization. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param options - Object containing name. * @returns {Promise} * @throws {BadRequestException} 400 @@ -241,7 +256,10 @@ export class Authorization { * * Get a list of all roles that apply to an organization. This includes both environment roles and custom roles, returned in priority order. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -261,9 +279,15 @@ export class Authorization { * * Retrieve a role that applies to an organization by its slug. This can return either an environment role or a custom role. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param slug - The slug of the role. - * @example "org-billing-admin" + * + * @example + * "org-billing-admin" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -283,9 +307,15 @@ export class Authorization { * * Update an existing custom role. Only the fields provided in the request body will be updated. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param slug - The slug of the role. - * @example "org-billing-admin" + * + * @example + * "org-billing-admin" + * * @param options - The request body. * @returns {Promise} * @throws {BadRequestException} 400 @@ -310,9 +340,15 @@ export class Authorization { * * Delete an existing custom role. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param slug - The slug of the role. - * @example "org-admin" + * + * @example + * "org-admin" + * * @returns {Promise} * @throws {BadRequestException} 400 * @throws 403 response from the API. @@ -333,9 +369,15 @@ export class Authorization { * * Replace all permissions on a custom role with the provided list. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param slug - The slug of the role. - * @example "org-admin" + * + * @example + * "org-admin" + * * @param options - Object containing permissions. * @returns {Promise} * @throws 403 response from the API. @@ -359,9 +401,15 @@ export class Authorization { * * Add a single permission to a custom role. If the permission is already assigned to the role, this operation has no effect. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param slug - The slug of the role. - * @example "org-admin" + * + * @example + * "org-admin" + * * @param options - Object containing slug. * @returns {Promise} * @throws {BadRequestException} 400 @@ -386,11 +434,20 @@ export class Authorization { * * Remove a single permission from a custom role by its slug. * @param organizationId - The ID of the organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param slug - The slug of the role. - * @example "org-admin" + * + * @example + * "org-admin" + * * @param permissionSlug - The slug of the permission to remove. - * @example "documents:read" + * + * @example + * "documents:read" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -460,7 +517,10 @@ export class Authorization { * * Retrieve a permission by its unique slug. * @param slug - A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. - * @example "documents:read" + * + * @example + * "documents:read" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -476,7 +536,10 @@ export class Authorization { * * Update an existing permission. Only the fields provided in the request body will be updated. * @param slug - A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. - * @example "documents:read" + * + * @example + * "documents:read" + * * @param options - The request body. * @returns {Promise} * @throws 403 response from the API. @@ -499,7 +562,10 @@ export class Authorization { * * Delete an existing permission. System permissions cannot be deleted. * @param slug - A unique key to reference the permission. Must be lowercase and contain only letters, numbers, hyphens, underscores, colons, periods, and asterisks. - * @example "documents:read" + * + * @example + * "documents:read" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -513,7 +579,10 @@ export class Authorization { * * Retrieve the details of an authorization resource by its ID. * @param resourceId - The ID of the authorization resource. - * @example "authz_resource_01HXYZ123456789ABCDEFGHIJ" + * + * @example + * "authz_resource_01HXYZ123456789ABCDEFGHIJ" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -576,7 +645,6 @@ export class Authorization { * Delete an authorization resource and all its descendants. * @param options.cascadeDelete - If true, deletes all descendant resources and role assignments. If not set and the resource has children or assignments, the request will fail. * @default false - * @example false * @param options - Additional query options. * @returns {Promise} * @throws {BadRequestException} 400 @@ -640,11 +708,20 @@ export class Authorization { * * Retrieve the details of an authorization resource by its external ID, organization, and resource type. This is useful when you only have the external ID from your system and need to fetch the full resource details. * @param organizationId - The ID of the organization that owns the resource. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param resourceTypeSlug - The slug of the resource type. - * @example "project" + * + * @example + * "project" + * * @param externalId - An identifier you provide to reference the resource in your system. - * @example "proj-456" + * + * @example + * "proj-456" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -664,11 +741,20 @@ export class Authorization { * * Update an existing authorization resource using its external ID. * @param organizationId - The ID of the organization that owns the resource. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param resourceTypeSlug - The slug of the resource type. - * @example "project" + * + * @example + * "project" + * * @param externalId - An identifier you provide to reference the resource in your system. - * @example "proj-456" + * + * @example + * "proj-456" + * * @param options - The request body. * @returns {Promise} * @throws {BadRequestException} 400 @@ -692,11 +778,20 @@ export class Authorization { * * Delete an authorization resource by organization, resource type, and external ID. This also deletes all descendant resources. * @param organizationId - The ID of the organization that owns the resource. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param resourceTypeSlug - The slug of the resource type. - * @example "project" + * + * @example + * "project" + * * @param externalId - An identifier you provide to reference the resource in your system. - * @example "proj-456" + * + * @example + * "proj-456" + * * @param options - Additional query options. * @returns {Promise} * @throws {BadRequestException} 400 @@ -746,7 +841,10 @@ export class Authorization { * * List all role assignments for an organization membership. This returns all roles that have been assigned to the user on resources, including organization-level and sub-resource roles. * @param organizationMembershipId - The ID of the organization membership. - * @example "om_01HXYZ123456789ABCDEFGHIJ" + * + * @example + * "om_01HXYZ123456789ABCDEFGHIJ" + * * @param options - Pagination and filter options. * @returns {Promise>} * @throws 403 response from the API. @@ -815,9 +913,15 @@ export class Authorization { * * Remove a role assignment using its ID. * @param organizationMembershipId - The ID of the organization membership. - * @example "om_01HXYZ123456789ABCDEFGHIJ" + * + * @example + * "om_01HXYZ123456789ABCDEFGHIJ" + * * @param roleAssignmentId - The ID of the role assignment to remove. - * @example "role_assignment_01HXYZ123456789ABCDEFGH" + * + * @example + * "role_assignment_01HXYZ123456789ABCDEFGH" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -837,7 +941,10 @@ export class Authorization { * * You must provide either `parent_resource_id` or both `parent_resource_external_id` and `parent_resource_type_slug` to identify the parent resource. * @param organizationMembershipId - The ID of the organization membership. - * @example "om_01HXYZ123456789ABCDEFGHIJ" + * + * @example + * "om_01HXYZ123456789ABCDEFGHIJ" + * * @param options - Pagination and filter options. * @returns {Promise>} * @throws {BadRequestException} 400 @@ -918,11 +1025,20 @@ export class Authorization { * * Returns all organization memberships that have a specific permission on a resource, using the resource's external ID. This is useful for answering "Who can access this resource?" when you only have the external ID. * @param organizationId - The ID of the organization that owns the resource. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param resourceTypeSlug - The slug of the resource type this resource belongs to. - * @example "project" + * + * @example + * "project" + * * @param externalId - An identifier you provide to reference the resource in your system. - * @example "proj-456" + * + * @example + * "proj-456" + * * @param options - Pagination and filter options. * @returns {Promise>} * @throws {BadRequestException} 400 @@ -966,9 +1082,15 @@ export class Authorization { * * Returns all permissions the organization membership effectively has on a resource, including permissions inherited through roles assigned to ancestor resources. * @param organizationMembershipId - The ID of the organization membership. - * @example "om_01HXYZ123456789ABCDEFGHIJ" + * + * @example + * "om_01HXYZ123456789ABCDEFGHIJ" + * * @param resourceId - The ID of the authorization resource. - * @example "authz_resource_01HXYZ123456789ABCDEFGHIJ" + * + * @example + * "authz_resource_01HXYZ123456789ABCDEFGHIJ" + * * @param options - Pagination and filter options. * @returns {Promise>} * @throws 403 response from the API. diff --git a/src/directory-sync/directory-sync.ts b/src/directory-sync/directory-sync.ts index e7b3723ee..c733f62da 100644 --- a/src/directory-sync/directory-sync.ts +++ b/src/directory-sync/directory-sync.ts @@ -59,7 +59,10 @@ export class DirectorySync { * * Get the details of an existing directory. * @param id - Unique identifier for the Directory. - * @example "directory_01ECAZ4NV9QMV47GW873HDCX74" + * + * @example + * "directory_01ECAZ4NV9QMV47GW873HDCX74" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -77,7 +80,10 @@ export class DirectorySync { * * Permanently deletes an existing directory. It cannot be undone. * @param id - Unique identifier for the Directory. - * @example "directory_01ECAZ4NV9QMV47GW873HDCX74" + * + * @example + * "directory_01ECAZ4NV9QMV47GW873HDCX74" + * * @returns {Promise} * @throws 403 response from the API. */ diff --git a/src/feature-flags/feature-flags.ts b/src/feature-flags/feature-flags.ts index fca1fd324..58e8b178e 100644 --- a/src/feature-flags/feature-flags.ts +++ b/src/feature-flags/feature-flags.ts @@ -53,7 +53,10 @@ export class FeatureFlags { * * Get the details of an existing feature flag by its slug. * @param slug - A unique key to reference the Feature Flag. - * @example "advanced-analytics" + * + * @example + * "advanced-analytics" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -70,7 +73,10 @@ export class FeatureFlags { * * Enables a feature flag in the current environment. * @param slug - A unique key to reference the Feature Flag. - * @example "advanced-analytics" + * + * @example + * "advanced-analytics" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -88,7 +94,10 @@ export class FeatureFlags { * * Disables a feature flag in the current environment. * @param slug - A unique key to reference the Feature Flag. - * @example "advanced-analytics" + * + * @example + * "advanced-analytics" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -134,7 +143,10 @@ export class FeatureFlags { * * Get a list of all enabled feature flags for an organization. * @param organizationId - Unique identifier of the Organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @param options - Pagination and filter options. * @returns {Promise>} * @throws {NotFoundException} 404 @@ -167,7 +179,10 @@ export class FeatureFlags { * * Get a list of all enabled feature flags for the provided user. This includes feature flags enabled specifically for the user as well as any organizations that the user is a member of. * @param userId - The ID of the user. - * @example "user_01E4ZCR3C56J083X43JQXF3JK5" + * + * @example + * "user_01E4ZCR3C56J083X43JQXF3JK5" + * * @param options - Pagination and filter options. * @returns {Promise>} * @throws {NotFoundException} 404 diff --git a/src/multi-factor-auth/multi-factor-auth.ts b/src/multi-factor-auth/multi-factor-auth.ts index 4df15e265..ad52db28a 100644 --- a/src/multi-factor-auth/multi-factor-auth.ts +++ b/src/multi-factor-auth/multi-factor-auth.ts @@ -43,7 +43,10 @@ export class MultiFactorAuth { * * Permanently deletes an Authentication Factor. It cannot be undone. * @param id - The unique ID of the Factor. - * @example "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * + * @example + * "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -56,7 +59,10 @@ export class MultiFactorAuth { * * Gets an Authentication Factor. * @param id - The unique ID of the Factor. - * @example "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * + * @example + * "auth_factor_01FVYZ5QM8N98T9ME5BCB2BBMJ" + * * @returns {Promise} * @throws {NotFoundException} 404 */ diff --git a/src/organization-domains/organization-domains.ts b/src/organization-domains/organization-domains.ts index cd84b6ec3..67193ddcc 100644 --- a/src/organization-domains/organization-domains.ts +++ b/src/organization-domains/organization-domains.ts @@ -15,7 +15,10 @@ export class OrganizationDomains { * * Get the details of an existing organization domain. * @param id - Unique identifier of the organization domain. - * @example "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * + * @example + * "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -32,7 +35,10 @@ export class OrganizationDomains { * * Initiates verification process for an Organization Domain. * @param id - Unique identifier of the organization domain. - * @example "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * + * @example + * "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * * @returns {Promise} * @throws {BadRequestException} 400 */ @@ -69,7 +75,10 @@ export class OrganizationDomains { * * Permanently deletes an organization domain. It cannot be undone. * @param id - Unique identifier of the organization domain. - * @example "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * + * @example + * "org_domain_01EHZNVPK2QXHMVWCEDQEKY69A" + * * @returns {Promise} * @throws {NotFoundException} 404 */ diff --git a/src/organizations/organizations.ts b/src/organizations/organizations.ts index 87f18a2a9..4f2053471 100644 --- a/src/organizations/organizations.ts +++ b/src/organizations/organizations.ts @@ -76,7 +76,10 @@ export class Organizations { * * Permanently deletes an organization in the current environment. It cannot be undone. * @param id - Unique identifier of the Organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @returns {Promise} * @throws 403 response from the API. */ @@ -89,7 +92,10 @@ export class Organizations { * * Get the details of an existing organization. * @param id - Unique identifier of the Organization. - * @example "org_01EHZNVPK3SFK441A1RGBFSHRT" + * + * @example + * "org_01EHZNVPK3SFK441A1RGBFSHRT" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -106,7 +112,10 @@ export class Organizations { * * Get the details of an existing organization by an [external identifier](https://workos.com/docs/authkit/metadata/external-identifiers). * @param externalId - The external ID of the Organization. - * @example "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191" + * + * @example + * "2fe01467-f7ea-4dd2-8b79-c2b4f56d0191" + * * @returns {Promise} * @throws {NotFoundException} 404 */ diff --git a/src/sso/sso.ts b/src/sso/sso.ts index e8b851944..5ec2e8ebb 100644 --- a/src/sso/sso.ts +++ b/src/sso/sso.ts @@ -61,7 +61,10 @@ export class SSO { * * Permanently deletes an existing connection. It cannot be undone. * @param id - Unique identifier for the Connection. - * @example "conn_01E4ZCR3C56J083X43JQXF3JK5" + * + * @example + * "conn_01E4ZCR3C56J083X43JQXF3JK5" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -193,7 +196,10 @@ export class SSO { * * Get the details of an existing connection. * @param id - Unique identifier for the Connection. - * @example "conn_01E4ZCR3C56J083X43JQXF3JK5" + * + * @example + * "conn_01E4ZCR3C56J083X43JQXF3JK5" + * * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 diff --git a/src/user-management/user-management.ts b/src/user-management/user-management.ts index 792060ed4..ea2119615 100644 --- a/src/user-management/user-management.ts +++ b/src/user-management/user-management.ts @@ -231,7 +231,10 @@ export class UserManagement { * * Get the details of an existing user by an [external identifier](https://workos.com/docs/authkit/metadata/external-identifiers). * @param externalId - The external ID of the user. - * @example "f1ffa2b2-c20b-4d39-be5c-212726e11222" + * + * @example + * "f1ffa2b2-c20b-4d39-be5c-212726e11222" + * * @returns {Promise} * @throws {NotFoundException} 404 */ @@ -1462,9 +1465,15 @@ export class UserManagement { * * Logout a user from the current [session](https://workos.com/docs/reference/authkit/session). * @param options.sessionId - The ID of the session to revoke. This can be extracted from the `sid` claim of the access token. - * @example "session_01H93ZY4F80QPBEZ1R5B2SHQG8" + * + * @example + * "session_01H93ZY4F80QPBEZ1R5B2SHQG8" + * * @param options.returnTo - The URL to redirect the user to after session revocation. - * @example "https://example.com" + * + * @example + * "https://example.com" + * * @returns {string} * @throws {UnprocessableEntityException} 422 */ From e29207a6b5021c29a3cc37aff67f60c110aceeea Mon Sep 17 00:00:00 2001 From: "Garen J. Torikian" Date: Tue, 21 Apr 2026 13:01:01 -0400 Subject: [PATCH 5/5] more bot feedback --- src/directory-sync/directory-sync.ts | 8 ++++++++ src/feature-flags/feature-flags.ts | 17 ++++------------- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/src/directory-sync/directory-sync.ts b/src/directory-sync/directory-sync.ts index c733f62da..021acf0e6 100644 --- a/src/directory-sync/directory-sync.ts +++ b/src/directory-sync/directory-sync.ts @@ -169,6 +169,10 @@ export class DirectorySync { * Get a Directory User * * Get the details of an existing Directory User. + * @param user - Unique identifier for the Directory User. + * + * @example + * "directory_user_01E1JG7J09H96KYP8HM9B0G5SJ" * @returns {Promise>} * @throws 403 response from the API. * @throws {NotFoundException} 404 @@ -187,6 +191,10 @@ export class DirectorySync { * Get a Directory Group * * Get the details of an existing Directory Group. + * @param group - Unique identifier for the Directory Group. + * + * @example + * "directory_group_01E1JJS84MFPPQ3G655FHTKX6Z" * @returns {Promise} * @throws 403 response from the API. * @throws {NotFoundException} 404 diff --git a/src/feature-flags/feature-flags.ts b/src/feature-flags/feature-flags.ts index 58e8b178e..e8e706389 100644 --- a/src/feature-flags/feature-flags.ts +++ b/src/feature-flags/feature-flags.ts @@ -22,7 +22,7 @@ export class FeatureFlags { * * Get a list of all of your existing feature flags matching the criteria specified. * @param options - Pagination and filter options. - * @returns {Promise>} + * @returns {Promise>} * @throws {BadRequestException} 400 * @throws {NotFoundException} 404 * @throws {UnprocessableEntityException} 422 @@ -114,6 +114,7 @@ export class FeatureFlags { * Add a feature flag target * * Enables a feature flag for a specific target in the current environment. Currently, supported targets include users and organizations. + * @params options - Object containing slug and targetId. * @returns {Promise} * @throws {BadRequestException} 400 * @throws 403 response from the API. @@ -128,6 +129,7 @@ export class FeatureFlags { * Remove a feature flag target * * Removes a target from the feature flag's target list in the current environment. Currently, supported targets include users and organizations. + * @params options - Object containing slug and targetId. * @returns {Promise} * @throws {BadRequestException} 400 * @throws 403 response from the API. @@ -142,13 +144,8 @@ export class FeatureFlags { * List enabled feature flags for an organization * * Get a list of all enabled feature flags for an organization. - * @param organizationId - Unique identifier of the Organization. - * - * @example - * "org_01EHZNVPK3SFK441A1RGBFSHRT" - * * @param options - Pagination and filter options. - * @returns {Promise>} + * @returns {Promise>} * @throws {NotFoundException} 404 */ async listOrganizationFeatureFlags( @@ -177,12 +174,6 @@ export class FeatureFlags { /** * List enabled feature flags for a user * - * Get a list of all enabled feature flags for the provided user. This includes feature flags enabled specifically for the user as well as any organizations that the user is a member of. - * @param userId - The ID of the user. - * - * @example - * "user_01E4ZCR3C56J083X43JQXF3JK5" - * * @param options - Pagination and filter options. * @returns {Promise>} * @throws {NotFoundException} 404