featurebase-node 0.13.0 → 0.14.1

package/src/resources/audit-logs.ts

@@ -0,0 +1,607 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { CursorPage, type CursorPageParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+
+/**
+ * Audit logs provide a chronological record of significant admin actions in your organization. Use them for security auditing, compliance reporting, and tracking workspace changes.
+ */
+export class AuditLogs extends APIResource {
+  /**
+   * Returns a list of audit log events in your organization using cursor-based
+   * pagination (newest first).
+   *
+   * ### Query Parameters
+   *
+   * - `limit` - Number of events to return (1-100, default 10)
+   * - `cursor` - Cursor from a previous response for pagination
+   * - `action` - Filter by action type (e.g. `webhook.deleted`,
+   *   `security.sso_enabled`)
+   * - `domain` - Filter by domain/category (e.g. `security`, `messenger`)
+   * - `startDate` - Filter events created on or after this ISO 8601 datetime
+   * - `endDate` - Filter events created on or before this ISO 8601 datetime
+   *
+   * ### Filtering by Action
+   *
+   * The `action` parameter filters by event type. Each action follows the
+   * `{domain}.{verb}` convention. See the `action` enum in this schema for the full
+   * list of supported values.
+   *
+   * **Examples:**
+   *
+   * - `?action=security.sso_enabled` — only SSO enablement events
+   * - `?action=webhook.deleted` — only webhook deletion events
+   *
+   * ### Filtering by Domain
+   *
+   * Use the `domain` parameter to narrow results to one category of audit event.
+   *
+   * **Examples:**
+   *
+   * - `?domain=security` — only security-related audit events
+   * - `?domain=messenger` — only messenger-related audit events
+   *
+   * ### Filtering by Date Range
+   *
+   * Use `startDate` and `endDate` together or individually to narrow results to a
+   * time window.
+   *
+   * **Examples:**
+   *
+   * - `?startDate=2025-01-01T00:00:00Z&endDate=2025-01-31T23:59:59Z` — January 2025
+   *   only
+   * - `?startDate=2025-06-01T00:00:00Z` — from June 1st onward
+   *
+   * ### Pagination
+   *
+   * Results are ordered by `createdAt` descending (newest first). Use the
+   * `nextCursor` value from each response as the `cursor` parameter in the next
+   * request to paginate forward.
+   *
+   * ```
+   * GET /v2/audit-logs?limit=20
+   * → { "nextCursor": "eyJ..." }
+   *
+   * GET /v2/audit-logs?limit=20&cursor=eyJ...
+   * → { "nextCursor": null }   ← no more results
+   * ```
+   *
+   * ### Metadata
+   *
+   * The `metadata` field contains event-specific details (e.g. before/after state
+   * for updates). Its shape depends on the `action` type and is not strictly modeled
+   * in the schema — treat it as a free-form object.
+   *
+   * ### Response Format
+   *
+   * Returns a list object with:
+   *
+   * - `object` - Always `"list"`
+   * - `data` - Array of audit log objects
+   * - `nextCursor` - Cursor for the next page, or `null` if no more results
+   *
+   * ### Audit Log Object
+   *
+   * Each audit log includes:
+   *
+   * - `id` - Unique event identifier (UUID)
+   * - `correlationId` - Groups related events from a single operation (e.g. bulk
+   *   import)
+   * - `action` - What happened (e.g. `webhook.deleted`)
+   * - `domain` - Category the action belongs to (e.g. `integrations`)
+   * - `description` - Human-readable description
+   * - `actor` - Who performed the action (id, type, email, name, apiKey)
+   * - `resource` - What was affected (type, id, name)
+   * - `request` - Request context (ipAddress, userAgent)
+   * - `metadata` - Event-specific payload
+   * - `createdAt` - When the event occurred
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   */
+  list(
+    params: AuditLogListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AuditLogListResponsesCursorPage, AuditLogListResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...query } = params ?? {};
+    return this._client.getAPIList('/v2/audit-logs', CursorPage<AuditLogListResponse>, {
+      query,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+}
+
+export type AuditLogListResponsesCursorPage = CursorPage<AuditLogListResponse>;
+
+export interface AuditLogListResponse {
+  /**
+   * Unique event identifier
+   */
+  id: string;
+
+  /**
+   * The type of action that was performed
+   */
+  action:
+    | 'auth.login'
+    | 'auth.logout'
+    | 'auth.login_failed'
+    | 'auth.password_reset_requested'
+    | 'auth.password_changed'
+    | 'auth.mfa_enabled'
+    | 'auth.mfa_disabled'
+    | 'auth.sso_login'
+    | 'auth.password_reset_completed'
+    | 'auth.unauthorized_method'
+    | 'auth.recovery_code_regenerated'
+    | 'auth.sso_enforcement_blocked'
+    | 'auth.sso_enforcement_session_invalidated'
+    | 'auth.managed_account_link_blocked'
+    | 'auth.cross_org_invite_accepted'
+    | 'auth.sso_enforcement_shadow'
+    | 'teammate.invited'
+    | 'teammate.joined'
+    | 'teammate.removed'
+    | 'teammate.email_changed'
+    | 'teammate.name_changed'
+    | 'teammate.seat_changed'
+    | 'teammate.deactivated'
+    | 'teammate.invite_changed'
+    | 'teammate.invite_deleted'
+    | 'teammate.scim_provisioned'
+    | 'teammate.scim_deprovisioned'
+    | 'teammate.scim_unlinked'
+    | 'teammate.scim_relinked'
+    | 'teammate.scim_operation_blocked'
+    | 'teammate.scim_seat_capacity_blocked'
+    | 'teammate.scim_email_updated'
+    | 'teammate.scim_exclusion_list_updated'
+    | 'teammate.restored'
+    | 'teammate.scim_restored'
+    | 'teammate.scim_auto_claimed'
+    | 'teammate.scim_claim_role_preserved'
+    | 'teammate.permanently_removed'
+    | 'member.role_changed'
+    | 'organization.owner_transferred'
+    | 'article.created'
+    | 'article.updated'
+    | 'article.published'
+    | 'article.unpublished'
+    | 'article.deleted'
+    | 'changelog.created'
+    | 'changelog.published'
+    | 'changelog.deleted'
+    | 'changelog.unpublished'
+    | 'settings.name_changed'
+    | 'settings.branding_updated'
+    | 'settings.custom_domain_changed'
+    | 'settings.language_changed'
+    | 'settings.timezone_changed'
+    | 'settings.email_settings_changed'
+    | 'settings.help_center_updated'
+    | 'settings.moderation_changed'
+    | 'settings.voting_changed'
+    | 'settings.statuses_updated'
+    | 'settings.boards_updated'
+    | 'settings.privacy_changed'
+    | 'settings.subdomain_changed'
+    | 'settings.subdomain_change_requested'
+    | 'settings.grace_period_changed'
+    | 'security.scim_override_blocked'
+    | 'security.sso_enabled'
+    | 'security.sso_disabled'
+    | 'security.sso_configured'
+    | 'security.sso_jit_provisioning_blocked'
+    | 'security.directory_sync_enabled'
+    | 'security.directory_sync_disabled'
+    | 'security.directory_sync_reconciled'
+    | 'security.two_factor_enforced'
+    | 'security.auth_method_changed'
+    | 'security.ip_allowlist_changed'
+    | 'security.ip_allowlist_blocked'
+    | 'security.identity_verification_changed'
+    | 'security.sso_url_changed'
+    | 'security.sso_jit_provisioning_changed'
+    | 'security.sso_enforcement_enabled'
+    | 'security.sso_enforcement_disabled'
+    | 'security.dsync_group_mappings_changed'
+    | 'security.dsync_mapping_priority_changed'
+    | 'security.user_banned'
+    | 'security.user_unbanned'
+    | 'integration.installed'
+    | 'integration.uninstalled'
+    | 'integration.configured'
+    | 'webhook.created'
+    | 'webhook.updated'
+    | 'webhook.deleted'
+    | 'webhook.secret_rotated'
+    | 'api_key.created'
+    | 'api_key.regenerated'
+    | 'api_key.deleted'
+    | 'organization.deletion_scheduled'
+    | 'organization.deletion_cancelled'
+    | 'data.export_initiated'
+    | 'data.import_initiated'
+    | 'data.bulk_delete'
+    | 'data.user_data_deleted'
+    | 'data.csv_exported'
+    | 'billing.plan_changed'
+    | 'billing.plan_cancelled'
+    | 'billing.seat_limit_changed'
+    | 'billing.seat_activated'
+    | 'workflow.created'
+    | 'workflow.activated'
+    | 'workflow.deactivated'
+    | 'workflow.deleted'
+    | 'workflow.updated'
+    | 'messenger.look_and_feel_changed'
+    | 'messenger.spaces_changed'
+    | 'messenger.language_changed'
+    | 'messenger.platform_availability_changed'
+    | 'messenger.search_browse_changed'
+    | 'messenger.email_collection_changed'
+    | 'messenger.welcome_message_changed'
+    | 'messenger.launcher_changed'
+    | 'messenger.inbound_conversations_changed'
+    | 'messenger.office_hours_changed'
+    | 'messenger.identity_verification_changed'
+    | 'messenger.privacy_policy_changed'
+    | 'brand.created'
+    | 'brand.updated'
+    | 'brand.deleted'
+    | 'brand.messenger_look_and_feel_changed'
+    | 'brand.messenger_launcher_changed'
+    | 'brand.messenger_welcome_message_changed'
+    | 'brand.messenger_privacy_policy_changed'
+    | 'brand.default_changed'
+    | 'ai_agent.enabled'
+    | 'ai_agent.disabled'
+    | 'ai_agent.identity_changed'
+    | 'ai_agent.customization_changed'
+    | 'ai_agent.guidance_changed'
+    | 'ai_agent.multilingual_changed'
+    | 'ai_agent.data_context_changed'
+    | 'email.sending_address_created'
+    | 'email.sending_address_updated'
+    | 'email.sending_address_deleted'
+    | 'email.domain_registered'
+    | 'email.domain_deleted'
+    | 'email.reply_to_changed'
+    | 'email.ignored_address_added'
+    | 'email.ignored_address_removed';
+
+  actor: AuditLogListResponse.Actor;
+
+  /**
+   * Groups related events from a single operation (e.g. bulk import)
+   */
+  correlationId: string | null;
+
+  /**
+   * ISO 8601 timestamp of when the event occurred
+   */
+  createdAt: string;
+
+  /**
+   * Pre-rendered human-readable description of the event
+   */
+  description: string;
+
+  /**
+   * The domain/category the action belongs to
+   */
+  domain:
+    | 'authentication'
+    | 'team_management'
+    | 'permissions'
+    | 'articles'
+    | 'changelog'
+    | 'workspace_settings'
+    | 'security'
+    | 'integrations'
+    | 'data_management'
+    | 'billing'
+    | 'workflows'
+    | 'messenger'
+    | 'brands'
+    | 'ai_agent'
+    | 'email_config';
+
+  /**
+   * Event-specific payload with before/after state when applicable. The shape of
+   * this object depends on the action type.
+   */
+  metadata: { [key: string]: unknown };
+
+  /**
+   * Object type identifier
+   */
+  object: 'audit_log';
+
+  request: AuditLogListResponse.Request;
+
+  resource: AuditLogListResponse.Resource;
+}
+
+export namespace AuditLogListResponse {
+  export interface Actor {
+    /**
+     * Featurebase user ID of the actor, or null for system actors
+     */
+    id: string | null;
+
+    /**
+     * API key that authenticated the request, or null for dashboard sessions
+     */
+    apiKey: Actor.APIKey | null;
+
+    /**
+     * Email address of the actor
+     */
+    email: string;
+
+    /**
+     * Display name of the actor
+     */
+    name: string | null;
+
+    /**
+     * The type of actor that performed the action
+     */
+    type: 'admin' | 'system' | 'api_key' | 'integration';
+  }
+
+  export namespace Actor {
+    /**
+     * API key that authenticated the request, or null for dashboard sessions
+     */
+    export interface APIKey {
+      /**
+       * API key ID
+       */
+      id: string;
+
+      /**
+       * API key name
+       */
+      name: string;
+    }
+  }
+
+  export interface Request {
+    /**
+     * IP address the request originated from
+     */
+    ipAddress: string | null;
+
+    /**
+     * User-Agent header from the request
+     */
+    userAgent: string | null;
+  }
+
+  export interface Resource {
+    /**
+     * ID of the affected resource, or null for organization-level events
+     */
+    id: string | null;
+
+    /**
+     * Display name of the affected resource
+     */
+    name: string | null;
+
+    /**
+     * Type of the affected resource
+     */
+    type: string;
+  }
+}
+
+export interface AuditLogListParams extends CursorPageParams {
+  /**
+   * Query param: Filter audit logs by action type
+   */
+  action?:
+    | 'auth.login'
+    | 'auth.logout'
+    | 'auth.login_failed'
+    | 'auth.password_reset_requested'
+    | 'auth.password_changed'
+    | 'auth.mfa_enabled'
+    | 'auth.mfa_disabled'
+    | 'auth.sso_login'
+    | 'auth.password_reset_completed'
+    | 'auth.unauthorized_method'
+    | 'auth.recovery_code_regenerated'
+    | 'auth.sso_enforcement_blocked'
+    | 'auth.sso_enforcement_session_invalidated'
+    | 'auth.managed_account_link_blocked'
+    | 'auth.cross_org_invite_accepted'
+    | 'auth.sso_enforcement_shadow'
+    | 'teammate.invited'
+    | 'teammate.joined'
+    | 'teammate.removed'
+    | 'teammate.email_changed'
+    | 'teammate.name_changed'
+    | 'teammate.seat_changed'
+    | 'teammate.deactivated'
+    | 'teammate.invite_changed'
+    | 'teammate.invite_deleted'
+    | 'teammate.scim_provisioned'
+    | 'teammate.scim_deprovisioned'
+    | 'teammate.scim_unlinked'
+    | 'teammate.scim_relinked'
+    | 'teammate.scim_operation_blocked'
+    | 'teammate.scim_seat_capacity_blocked'
+    | 'teammate.scim_email_updated'
+    | 'teammate.scim_exclusion_list_updated'
+    | 'teammate.restored'
+    | 'teammate.scim_restored'
+    | 'teammate.scim_auto_claimed'
+    | 'teammate.scim_claim_role_preserved'
+    | 'teammate.permanently_removed'
+    | 'member.role_changed'
+    | 'organization.owner_transferred'
+    | 'article.created'
+    | 'article.updated'
+    | 'article.published'
+    | 'article.unpublished'
+    | 'article.deleted'
+    | 'changelog.created'
+    | 'changelog.published'
+    | 'changelog.deleted'
+    | 'changelog.unpublished'
+    | 'settings.name_changed'
+    | 'settings.branding_updated'
+    | 'settings.custom_domain_changed'
+    | 'settings.language_changed'
+    | 'settings.timezone_changed'
+    | 'settings.email_settings_changed'
+    | 'settings.help_center_updated'
+    | 'settings.moderation_changed'
+    | 'settings.voting_changed'
+    | 'settings.statuses_updated'
+    | 'settings.boards_updated'
+    | 'settings.privacy_changed'
+    | 'settings.subdomain_changed'
+    | 'settings.subdomain_change_requested'
+    | 'settings.grace_period_changed'
+    | 'security.scim_override_blocked'
+    | 'security.sso_enabled'
+    | 'security.sso_disabled'
+    | 'security.sso_configured'
+    | 'security.sso_jit_provisioning_blocked'
+    | 'security.directory_sync_enabled'
+    | 'security.directory_sync_disabled'
+    | 'security.directory_sync_reconciled'
+    | 'security.two_factor_enforced'
+    | 'security.auth_method_changed'
+    | 'security.ip_allowlist_changed'
+    | 'security.ip_allowlist_blocked'
+    | 'security.identity_verification_changed'
+    | 'security.sso_url_changed'
+    | 'security.sso_jit_provisioning_changed'
+    | 'security.sso_enforcement_enabled'
+    | 'security.sso_enforcement_disabled'
+    | 'security.dsync_group_mappings_changed'
+    | 'security.dsync_mapping_priority_changed'
+    | 'security.user_banned'
+    | 'security.user_unbanned'
+    | 'integration.installed'
+    | 'integration.uninstalled'
+    | 'integration.configured'
+    | 'webhook.created'
+    | 'webhook.updated'
+    | 'webhook.deleted'
+    | 'webhook.secret_rotated'
+    | 'api_key.created'
+    | 'api_key.regenerated'
+    | 'api_key.deleted'
+    | 'organization.deletion_scheduled'
+    | 'organization.deletion_cancelled'
+    | 'data.export_initiated'
+    | 'data.import_initiated'
+    | 'data.bulk_delete'
+    | 'data.user_data_deleted'
+    | 'data.csv_exported'
+    | 'billing.plan_changed'
+    | 'billing.plan_cancelled'
+    | 'billing.seat_limit_changed'
+    | 'billing.seat_activated'
+    | 'workflow.created'
+    | 'workflow.activated'
+    | 'workflow.deactivated'
+    | 'workflow.deleted'
+    | 'workflow.updated'
+    | 'messenger.look_and_feel_changed'
+    | 'messenger.spaces_changed'
+    | 'messenger.language_changed'
+    | 'messenger.platform_availability_changed'
+    | 'messenger.search_browse_changed'
+    | 'messenger.email_collection_changed'
+    | 'messenger.welcome_message_changed'
+    | 'messenger.launcher_changed'
+    | 'messenger.inbound_conversations_changed'
+    | 'messenger.office_hours_changed'
+    | 'messenger.identity_verification_changed'
+    | 'messenger.privacy_policy_changed'
+    | 'brand.created'
+    | 'brand.updated'
+    | 'brand.deleted'
+    | 'brand.messenger_look_and_feel_changed'
+    | 'brand.messenger_launcher_changed'
+    | 'brand.messenger_welcome_message_changed'
+    | 'brand.messenger_privacy_policy_changed'
+    | 'brand.default_changed'
+    | 'ai_agent.enabled'
+    | 'ai_agent.disabled'
+    | 'ai_agent.identity_changed'
+    | 'ai_agent.customization_changed'
+    | 'ai_agent.guidance_changed'
+    | 'ai_agent.multilingual_changed'
+    | 'ai_agent.data_context_changed'
+    | 'email.sending_address_created'
+    | 'email.sending_address_updated'
+    | 'email.sending_address_deleted'
+    | 'email.domain_registered'
+    | 'email.domain_deleted'
+    | 'email.reply_to_changed'
+    | 'email.ignored_address_added'
+    | 'email.ignored_address_removed';
+
+  /**
+   * Query param: Filter audit logs by domain/category
+   */
+  domain?:
+    | 'authentication'
+    | 'team_management'
+    | 'permissions'
+    | 'articles'
+    | 'changelog'
+    | 'workspace_settings'
+    | 'security'
+    | 'integrations'
+    | 'data_management'
+    | 'billing'
+    | 'workflows'
+    | 'messenger'
+    | 'brands'
+    | 'ai_agent'
+    | 'email_config';
+
+  /**
+   * Query param: Filter events created on or before this ISO 8601 datetime
+   */
+  endDate?: string | null;
+
+  /**
+   * Query param: Filter events created on or after this ISO 8601 datetime
+   */
+  startDate?: string | null;
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
+export declare namespace AuditLogs {
+  export {
+    type AuditLogListResponse as AuditLogListResponse,
+    type AuditLogListResponsesCursorPage as AuditLogListResponsesCursorPage,
+    type AuditLogListParams as AuditLogListParams,
+  };
+}