@atlasauth/js 0.15.0 → 0.16.0

package/dist/organizations.d.ts

@@ -0,0 +1,330 @@
+import type { FapiClient } from './fapi';
+/**
+ * Organization self-management from the browser, over the Frontend API: the
+ * signed-in user's organizations, members, invitations, roles, teams, settings,
+ * membership requests, leaving and deleting. Cookie-authenticated through the
+ * {@link FapiClient}. Admin actions are gated by the user's role in the ACTIVE
+ * organization, exactly as the server enforces them.
+ *
+ * {@link OrganizationProfileController} is the headless state behind every SDK's
+ * `<OrganizationProfile>`: members, invitations and roles, with the actions an
+ * admin needs, as a subscribable store a framework renders.
+ */
+export interface ClientOrganization {
+    object: 'organization';
+    id: string;
+    name: string;
+    slug: string | null;
+    image_url?: string | null;
+    public_metadata?: Record<string, unknown>;
+    max_allowed_memberships?: number | null;
+    members_count?: number;
+    created_at?: number;
+    updated_at?: number;
+    /** On by-slug reads: the caller's own role. */
+    membership?: {
+        role: string;
+    };
+}
+export interface OrganizationMember {
+    object: 'organization_membership';
+    id: string;
+    role: string;
+    user: {
+        id: string;
+        first_name: string | null;
+        last_name: string | null;
+        image_url: string | null;
+    } | null;
+}
+export interface OrganizationInvitation {
+    object: 'organization_invitation';
+    id: string;
+    organization_id: string;
+    email_address: string;
+    role: string | null;
+    status: 'pending' | 'accepted' | 'revoked' | 'expired' | string;
+    inviter_user_id: string | null;
+    expires_at: number;
+    created_at: number;
+}
+/** What an accept page shows before the invitee signs in. */
+export interface PublicOrganizationInvitation {
+    object: 'organization_invitation';
+    id: string;
+    email_address: string;
+    role: string | null;
+    status: string;
+    expires_at: number;
+    organization: {
+        id: string;
+        name: string;
+        slug: string | null;
+        image_url: string | null;
+    };
+    inviter: {
+        first_name: string | null;
+        last_name: string | null;
+        image_url: string | null;
+    } | null;
+}
+export interface OrganizationRole {
+    object: 'role';
+    /** Present from servers that support per-organization custom roles. */
+    id?: string;
+    key: string;
+    name: string;
+    description: string | null;
+    is_system?: boolean;
+    /** Set on the organization's own custom roles; null for an instance-wide role. */
+    organization_id?: string | null;
+    /** Included only for a caller who manages members. */
+    permissions?: string[];
+    member_count?: number;
+}
+/** A permission an organization admin may put on a custom role. */
+export interface OrganizationPermission {
+    object: 'permission';
+    key: string;
+    name: string;
+    description: string | null;
+}
+/** What a custom role is made of. */
+export interface OrganizationRoleInput {
+    name?: string;
+    description?: string | null;
+    /** Permission keys; each must be one the caller holds. */
+    permissions?: string[];
+}
+export interface OrganizationTeam {
+    object: 'team';
+    id: string;
+    organization_id: string;
+    name: string;
+    description: string | null;
+    members_count?: number;
+    created_at: number;
+    updated_at: number;
+}
+export interface OrganizationTeamMember {
+    object: 'team_membership';
+    team_id: string;
+    user_id: string;
+    user: {
+        id: string;
+        first_name: string | null;
+        last_name: string | null;
+        image_url: string | null;
+    } | null;
+}
+export interface OrganizationSlugCheck {
+    object: 'organization_slug_check';
+    slug: string;
+    valid: boolean;
+    available: boolean;
+}
+export interface OrganizationPage<T> {
+    data: T[];
+    totalCount?: number;
+    hasMore: boolean;
+}
+/** A refused request. `code` is the server's stable error code. */
+export declare class OrganizationRequestError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly param?: string;
+    readonly reason?: string;
+    readonly meta?: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, param?: string, reason?: string, meta?: Record<string, unknown>);
+    /** True when the action needs a fresh re-authentication first (deleting an organization). */
+    get needsReverification(): boolean;
+}
+/** The organizations the signed-in user belongs to. */
+export declare function listMyOrganizations(client: FapiClient): Promise<OrganizationPage<Record<string, unknown>>>;
+export declare function createOrganization(client: FapiClient, input: {
+    name: string;
+    slug?: string;
+}): Promise<ClientOrganization>;
+/** The ACTIVE organization. */
+export declare function getOrganization(client: FapiClient, organizationId: string): Promise<ClientOrganization>;
+export declare function updateOrganization(client: FapiClient, organizationId: string, input: {
+    name?: string;
+    slug?: string;
+    image_url?: string | null;
+}): Promise<ClientOrganization>;
+/**
+ * Delete the active organization (admin only, when the application allows it).
+ * Needs a recent re-authentication: a stale session gets an error whose
+ * `needsReverification` is true.
+ */
+export declare function deleteOrganization(client: FapiClient, organizationId: string): Promise<{
+    object: 'organization';
+    id: string;
+    deleted: true;
+}>;
+/** Leave an organization (any member; the only admin must promote someone first). */
+export declare function leaveOrganization(client: FapiClient, organizationId: string): Promise<{
+    object: 'organization_membership';
+    organization_id: string;
+    user_id: string;
+    deleted: true;
+}>;
+export declare function checkOrganizationSlug(client: FapiClient, slug: string): Promise<OrganizationSlugCheck>;
+/** An organization the user belongs to, by slug (404 otherwise). */
+export declare function getOrganizationBySlug(client: FapiClient, slug: string): Promise<ClientOrganization>;
+/** The roles a member can hold (for a role picker). */
+export declare function listOrganizationRoles(client: FapiClient, organizationId: string): Promise<OrganizationRole[]>;
+/**
+ * The permissions the caller may put on a custom role: the instance's
+ * permissions that the caller holds (needs member management).
+ */
+export declare function listAssignablePermissions(client: FapiClient, organizationId: string): Promise<OrganizationPermission[]>;
+/** Create a custom role for the active organization (never past the caller's own permissions). */
+export declare function createOrganizationRole(client: FapiClient, organizationId: string, input: OrganizationRoleInput & {
+    key: string;
+    name: string;
+}): Promise<OrganizationRole>;
+/** Rename one of the organization's own roles or replace its permissions (the key is fixed). */
+export declare function updateOrganizationRole(client: FapiClient, organizationId: string, roleId: string, input: OrganizationRoleInput): Promise<OrganizationRole>;
+/**
+ * Delete one of the organization's own roles. A role still in use needs
+ * `reassignTo` (a role key) — its members and pending invitations move first.
+ */
+export declare function deleteOrganizationRole(client: FapiClient, organizationId: string, roleId: string, options?: {
+    reassignTo?: string;
+}): Promise<{
+    object: 'role';
+    id: string;
+    key: string;
+    deleted: true;
+    members_reassigned: number;
+}>;
+export declare function listOrganizationMembers(client: FapiClient, organizationId: string, options?: {
+    limit?: number;
+    offset?: number;
+}): Promise<OrganizationPage<OrganizationMember>>;
+export declare function updateMemberRole(client: FapiClient, organizationId: string, userId: string, role: string): Promise<{
+    object: 'organization_membership';
+    organization_id: string;
+    user_id: string;
+    role: string;
+}>;
+export declare function removeMember(client: FapiClient, organizationId: string, userId: string): Promise<unknown>;
+export declare function listOrganizationInvitations(client: FapiClient, organizationId: string, options?: {
+    status?: string;
+}): Promise<OrganizationPage<OrganizationInvitation>>;
+export declare function inviteMember(client: FapiClient, organizationId: string, input: {
+    emailAddress: string;
+    role: string;
+}): Promise<OrganizationInvitation>;
+export declare function revokeInvitation(client: FapiClient, organizationId: string, invitationId: string): Promise<OrganizationInvitation>;
+export declare function resendInvitation(client: FapiClient, organizationId: string, invitationId: string): Promise<OrganizationInvitation>;
+/** The public view of an invitation, for an accept page (no sign-in needed). */
+export declare function getOrganizationInvitation(client: FapiClient, invitationId: string): Promise<PublicOrganizationInvitation>;
+/** Accept an invitation by id as the signed-in user. */
+export declare function acceptOrganizationInvitation(client: FapiClient, invitationId: string): Promise<unknown>;
+/** Invitations addressed to the signed-in user. */
+export declare function listMyOrganizationInvitations(client: FapiClient): Promise<OrganizationPage<Record<string, unknown>>>;
+export declare function acceptMyOrganizationInvitation(client: FapiClient, invitationId: string): Promise<unknown>;
+export declare function declineMyOrganizationInvitation(client: FapiClient, invitationId: string): Promise<unknown>;
+/** Organizations the user could join (verified email domain matches). */
+export declare function listMyOrganizationSuggestions(client: FapiClient): Promise<OrganizationPage<Record<string, unknown>>>;
+export declare function acceptOrganizationSuggestion(client: FapiClient, organizationId: string): Promise<unknown>;
+export declare function listMembershipRequests(client: FapiClient, organizationId: string): Promise<OrganizationPage<Record<string, unknown>>>;
+export declare function acceptMembershipRequest(client: FapiClient, organizationId: string, requestId: string): Promise<unknown>;
+export declare function rejectMembershipRequest(client: FapiClient, organizationId: string, requestId: string): Promise<unknown>;
+export declare function getOrganizationSettings(client: FapiClient, organizationId: string): Promise<{
+    schema: Record<string, unknown> | null;
+    values: Record<string, unknown>;
+    version: number;
+}>;
+/** Write the organization's settings (admin; needs a recent re-authentication). */
+export declare function updateOrganizationSettings(client: FapiClient, organizationId: string, values: Record<string, unknown>): Promise<{
+    values: Record<string, unknown>;
+    version: number;
+}>;
+export declare function listTeams(client: FapiClient, organizationId: string): Promise<OrganizationTeam[]>;
+/** The caller's own teams, and the session's active team. */
+export declare function listMyTeams(client: FapiClient, organizationId: string): Promise<{
+    data: OrganizationTeam[];
+    activeTeamId: string | null;
+}>;
+export declare function createTeam(client: FapiClient, organizationId: string, input: {
+    name: string;
+    description?: string | null;
+}): Promise<OrganizationTeam>;
+export declare function updateTeam(client: FapiClient, organizationId: string, teamId: string, input: {
+    name?: string;
+    description?: string | null;
+}): Promise<OrganizationTeam>;
+export declare function deleteTeam(client: FapiClient, organizationId: string, teamId: string): Promise<unknown>;
+export declare function listTeamMembers(client: FapiClient, organizationId: string, teamId: string): Promise<OrganizationTeamMember[]>;
+export declare function addTeamMember(client: FapiClient, organizationId: string, teamId: string, userId: string): Promise<unknown>;
+export declare function removeTeamMember(client: FapiClient, organizationId: string, teamId: string, userId: string): Promise<unknown>;
+export interface OrganizationProfileState {
+    status: 'idle' | 'loading' | 'ready' | 'error';
+    members: OrganizationMember[];
+    membersTotal: number;
+    /** Pending invitations (admins only; empty for others). */
+    invitations: OrganizationInvitation[];
+    roles: OrganizationRole[];
+    /** Permissions an admin may put on a custom role (admins only; empty for others). */
+    permissions: OrganizationPermission[];
+    /** The last failure, for display. */
+    error: OrganizationRequestError | Error | null;
+    /** The action in flight (e.g. `invite`, `remove:<userId>`), or null. */
+    busy: string | null;
+}
+/**
+ * The state and actions behind `<OrganizationProfile>`, framework-free. Each
+ * SDK wraps it in its own reactivity (`subscribe` + `getState`). Admin-only
+ * reads (invitations) are skipped when `canManage` is false; a refused admin
+ * call surfaces as `error` rather than throwing out of an event handler.
+ */
+export declare class OrganizationProfileController {
+    private readonly client;
+    readonly organizationId: string;
+    private readonly options;
+    private state;
+    private readonly listeners;
+    constructor(client: FapiClient, organizationId: string, options?: {
+        canManage?: boolean;
+        onChange?: () => void | Promise<void>;
+    });
+    getState(): OrganizationProfileState;
+    subscribe(listener: (state: OrganizationProfileState) => void): () => void;
+    private set;
+    /** Load members, roles and (for admins) pending invitations. */
+    load(): Promise<void>;
+    private run;
+    changeRole(userId: string, role: string): Promise<{
+        object: "organization_membership";
+        organization_id: string;
+        user_id: string;
+        role: string;
+    } | undefined>;
+    removeMember(userId: string): Promise<unknown>;
+    invite(emailAddress: string, role: string): Promise<OrganizationInvitation | undefined>;
+    revokeInvitation(invitationId: string): Promise<OrganizationInvitation | undefined>;
+    resendInvitation(invitationId: string): Promise<OrganizationInvitation | undefined>;
+    /** The organization's own custom roles (a subset of `roles`). */
+    customRoles(): OrganizationRole[];
+    createRole(input: OrganizationRoleInput & {
+        key: string;
+        name: string;
+    }): Promise<OrganizationRole | undefined>;
+    updateRole(roleId: string, input: OrganizationRoleInput): Promise<OrganizationRole | undefined>;
+    deleteRole(roleId: string, options?: {
+        reassignTo?: string;
+    }): Promise<{
+        object: "role";
+        id: string;
+        key: string;
+        deleted: true;
+        members_reassigned: number;
+    } | undefined>;
+    /** Leave; `onChange` (e.g. a session reload) runs after. */
+    leave(): Promise<boolean>;
+    /** Delete (admin; may need re-authentication: check `error.needsReverification`). */
+    deleteOrganization(): Promise<boolean>;
+}