@adonis-agora/authkit-react 1.0.0-rc.2 → 1.0.0-rc.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @adonis-agora/authkit-react
 
+## 1.0.0-rc.3
+
+### Minor Changes
+
+- [#470](https://github.com/DavideCarvalho/adonis-agora-authkit/pull/470) [`d8ee87a`](https://github.com/DavideCarvalho/adonis-agora-authkit/commit/d8ee87abd875e8c141cde051023f1035d8274513) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - Account console extensions: other packages (and your app) can add pages to `/account/*`.
+  
+  - New subpath `@adonis-agora/authkit-server/account-extension` with the stable contract (`AccountExtension`, blocks, actions) and the `authkit.accountExtensions` registry binding. Contributors register from their provider's `boot()`; AuthKit renders the pages (Edge or your Inertia page) behind the account sign-in, with CSRF, sudo for sensitive actions, a per-account rate limit, and audit of external redirects.
+  - Blocks: `notice`, `keyValue`, `list`, `table`, `meter`, `actions`, `link`, `toolPreview` (approve/reject previews) and `component` (a provider's card fields, scripts loaded with the response's CSP nonce, with a link fallback).
+  - `accountConsole` in `config/authkit.ts`: one `subject(account, { activeOrg, tenant })` mapping shared by every extension, host overrides to disable, rename or reorder pages, and `loadTimeoutMs`.
+  - The account screens share one navigation (`accountNav`) that lists the mounted screens and the extension pages; `AuthHostRouteMap.account.extensions` lists the pages.
+  - JSON API: `GET {prefix}/api/extensions`, `GET {prefix}/api/x/:pageId`, `POST {prefix}/api/x/:pageId/actions/:action`.
+  - authkit-react: `<AccountExtensionPage>`, `useAccountExtensions()`, the page/action query options and `client.account.extensions.*`.
+
 ## 1.0.0-rc.2
 
 ### Minor Changes

package/build/index.d.ts

@@ -1,3 +1,6 @@
+export type { AccountExtensionPageProps, AccountExtensionProviderComponentProps, } from './src/account_extensions/account_extension_page.js';
+export { AccountExtensionPage, useAccountExtensionActionMutationOptions, useAccountExtensionPageQueryOptions, useAccountExtensions, useAccountExtensionsQueryOptions, } from './src/account_extensions/account_extension_page.js';
+export type { AccountExtensionActionButton, AccountExtensionActionDefinition, AccountExtensionActionField, AccountExtensionActionInput, AccountExtensionActionResult, AccountExtensionBlock, AccountExtensionPageResult, AccountExtensionPageView, AccountExtensionsResult, AccountExtensionValue, AccountNavEntry, } from './src/account_extensions/types.js';
 export type { AuthkitProviderProps } from './src/authkit_provider.js';
 export { AuthkitProvider } from './src/authkit_provider.js';
 export type { AuthkitClient, AuthkitClientOptions, } from './src/client/client.js';

package/build/index.js

@@ -1,3 +1,4 @@
+export { AccountExtensionPage, useAccountExtensionActionMutationOptions, useAccountExtensionPageQueryOptions, useAccountExtensions, useAccountExtensionsQueryOptions, } from './src/account_extensions/account_extension_page.js';
 export { AuthkitProvider } from './src/authkit_provider.js';
 export { AuthkitClientError, createAuthkitClient, } from './src/client/client.js';
 export { AuthkitClientProvider, createAuthkitQueryClient, useAuthkitClient, } from './src/client/context.js';

package/build/src/account_extensions/account_extension_page.d.ts

@@ -0,0 +1,42 @@
+import { type ComponentType } from 'react';
+import type { AuthkitClientError } from '../client/client.js';
+import type { AccountExtensionActionButton, AccountExtensionActionInput, AccountExtensionPageView, AccountExtensionsResult } from './types.js';
+export declare function useAccountExtensionsQueryOptions(): {
+    queryKey: readonly ["authkit", "account", "extensions"];
+    queryFn: () => Promise<AccountExtensionsResult>;
+};
+export declare function useAccountExtensionPageQueryOptions(pageId: string, query?: {
+    cursor?: string;
+    tab?: string;
+}): {
+    queryKey: readonly ["authkit", "account", "extensions", string, {
+        cursor?: string;
+        tab?: string;
+    }];
+    queryFn: () => Promise<import("./types.js").AccountExtensionPageResult>;
+};
+export declare function useAccountExtensionActionMutationOptions(pageId: string): {
+    mutationKey: readonly ['authkit', 'account', 'extensions', string, 'action'];
+    mutationFn: (input: {
+        action: string;
+    } & AccountExtensionActionInput) => Promise<import("./types.js").AccountExtensionActionResult>;
+};
+export declare function useAccountExtensions(): import("@tanstack/react-query").UseQueryResult<AccountExtensionsResult, AuthkitClientError>;
+export interface AccountExtensionProviderComponentProps {
+    provider: string;
+    props: Record<string, unknown>;
+    submit: AccountExtensionActionButton | null;
+    onSubmit?: (input: AccountExtensionActionInput) => void;
+}
+export interface AccountExtensionPageProps {
+    view: AccountExtensionPageView;
+    onAction?: (button: AccountExtensionActionButton, input?: AccountExtensionActionInput) => void;
+    csrfToken?: string;
+    loadComponent?: (provider: string) => ComponentType<AccountExtensionProviderComponentProps> | null | Promise<ComponentType<AccountExtensionProviderComponentProps> | null>;
+    nextLabel?: string;
+    className?: string;
+}
+export declare function AccountExtensionPage(props: AccountExtensionPageProps): import("react").DetailedReactHTMLElement<{
+    className: string | undefined;
+    'data-account-extension': string;
+}, HTMLElement>;

package/build/src/account_extensions/account_extension_page.js

@@ -0,0 +1,144 @@
+import { useQuery } from '@tanstack/react-query';
+import { createElement, useEffect, useState } from 'react';
+import { useAuthkitClient } from '../client/context.js';
+import { authkitKeys } from '../queries/keys.js';
+export function useAccountExtensionsQueryOptions() {
+    const client = useAuthkitClient();
+    return {
+        queryKey: authkitKeys.account.extensions(),
+        queryFn: () => client.account.extensions.list(),
+    };
+}
+export function useAccountExtensionPageQueryOptions(pageId, query) {
+    const client = useAuthkitClient();
+    return {
+        queryKey: authkitKeys.account.extensionPage(pageId, query),
+        queryFn: () => client.account.extensions.page(pageId, query),
+    };
+}
+export function useAccountExtensionActionMutationOptions(pageId) {
+    const client = useAuthkitClient();
+    return {
+        mutationKey: ['authkit', 'account', 'extensions', pageId, 'action'],
+        mutationFn: (input) => client.account.extensions.action(pageId, input.action, {
+            target: input.target ?? null,
+            fields: input.fields ?? {},
+        }),
+    };
+}
+export function useAccountExtensions() {
+    return useQuery(useAccountExtensionsQueryOptions());
+}
+const e = createElement;
+function Value({ value }) {
+    if (value.type === 'date' && value.iso) {
+        return e('time', { dateTime: value.iso, 'data-value': 'date' }, value.text);
+    }
+    return e('span', {
+        'data-value': value.type,
+        ...(value.type === 'badge' ? { 'data-tone': value.tone ?? 'neutral' } : {}),
+    }, value.text);
+}
+function ActionButtons({ actions, onAction, csrfToken, }) {
+    if (actions.length === 0)
+        return null;
+    return e('span', { 'data-actions': '' }, actions.map((button) => {
+        const key = `${button.action}:${button.target ?? ''}`;
+        const common = { 'data-action': button.action, 'data-tone': button.tone };
+        if (onAction) {
+            return e('button', { key, type: 'button', ...common, onClick: () => onAction(button) }, button.label);
+        }
+        if (button.step)
+            return e('a', { key, href: button.href, ...common }, button.label);
+        return e('form', { key, method: 'post', action: button.href }, e('input', { type: 'hidden', name: '_csrf', value: csrfToken ?? '' }), button.target !== null
+            ? e('input', { type: 'hidden', name: 'target', value: button.target })
+            : null, e('button', { type: 'submit', ...common }, button.label));
+    }));
+}
+function ProviderComponent({ block, loadComponent, onAction, }) {
+    const [Loaded, setLoaded] = useState(null);
+    useEffect(() => {
+        let alive = true;
+        if (!loadComponent)
+            return;
+        Promise.resolve(loadComponent(block.provider))
+            .then((component) => {
+            if (alive && component)
+                setLoaded(() => component);
+        })
+            .catch(() => { });
+        return () => {
+            alive = false;
+        };
+    }, [block.provider, loadComponent]);
+    const fallback = block.fallback
+        ? e('a', {
+            href: block.fallback.href,
+            'data-component-fallback': '',
+            ...(block.fallback.external ? { rel: 'noopener' } : {}),
+        }, block.fallback.label)
+        : null;
+    return e('div', { 'data-block': 'component', 'data-provider': block.provider }, Loaded
+        ? e(Loaded, {
+            provider: block.provider,
+            props: block.props,
+            submit: block.submit,
+            ...(onAction && block.submit
+                ? {
+                    onSubmit: (input) => onAction(block.submit, input),
+                }
+                : {}),
+        })
+        : fallback);
+}
+function Block({ block, props, }) {
+    const actions = (list) => e(ActionButtons, { actions: list, onAction: props.onAction, csrfToken: props.csrfToken });
+    const next = (href) => href ? e('a', { href, rel: 'next', 'data-next': '' }, props.nextLabel ?? 'Next page') : null;
+    switch (block.kind) {
+        case 'notice':
+            return e('div', { 'data-block': 'notice', 'data-tone': block.tone, role: 'status' }, block.text);
+        case 'keyValue':
+            return e('section', { 'data-block': 'keyValue' }, block.title ? e('h2', null, block.title) : null, e('dl', null, block.rows.map((row, i) => e('div', { key: i }, e('dt', null, row.label), e('dd', null, e(Value, { value: row.value }))))), actions(block.actions));
+        case 'list':
+            return e('section', { 'data-block': 'list' }, block.title ? e('h2', null, block.title) : null, block.items.length === 0
+                ? e('p', { 'data-empty': '' }, block.empty)
+                : e('ul', null, block.items.map((item, i) => e('li', { key: i }, item.href
+                    ? e('a', {
+                        href: item.href,
+                        ...(item.external ? { rel: 'noopener', target: '_blank' } : {}),
+                    }, item.title)
+                    : e('span', null, item.title), item.subtitle ? e('small', null, item.subtitle) : null, item.meta.map((value, j) => e(Value, { key: j, value })), item.badge ? e(Value, { value: item.badge }) : null, actions(item.actions)))), next(block.nextHref));
+        case 'table':
+            return e('section', { 'data-block': 'table' }, block.title ? e('h2', null, block.title) : null, block.rows.length === 0
+                ? e('p', { 'data-empty': '' }, block.empty)
+                : e('table', null, e('thead', null, e('tr', null, block.columns.map((c) => e('th', { key: c.id, scope: 'col' }, c.label)), block.hasActions ? e('th', { scope: 'col' }) : null)), e('tbody', null, block.rows.map((row, i) => e('tr', { key: i }, row.cells.map((value, j) => e('td', { key: j }, e(Value, { value }))), block.hasActions ? e('td', null, actions(row.actions)) : null)))), next(block.nextHref));
+        case 'meter':
+            return e('section', { 'data-block': 'meter' }, e('span', null, block.label), e('span', null, block.text), block.percent !== null ? e('progress', { max: 100, value: block.percent }) : null, block.resetsAt ? e(Value, { value: block.resetsAt }) : null);
+        case 'actions':
+            return e('div', { 'data-block': 'actions' }, actions(block.items));
+        case 'link':
+            return e('a', {
+                'data-block': 'link',
+                href: block.href,
+                ...(block.external ? { rel: 'noopener', target: '_blank' } : {}),
+            }, block.label);
+        case 'toolPreview':
+            return e('section', { 'data-block': 'toolPreview' }, e('h2', null, block.title), block.tool ? e('code', null, block.tool) : null, block.subtitle ? e('small', null, block.subtitle) : null, block.args.length > 0
+                ? e('dl', null, block.args.map((arg, i) => e('div', { key: i }, e('dt', null, arg.label), e('dd', null, e(Value, { value: arg.value })))))
+                : null, block.body ? e('pre', { 'data-format': block.body.format }, block.body.content) : null, actions(block.actions));
+        case 'component':
+            return e(ProviderComponent, {
+                block,
+                loadComponent: props.loadComponent,
+                onAction: props.onAction,
+            });
+        default:
+            return null;
+    }
+}
+export function AccountExtensionPage(props) {
+    const { view } = props;
+    return e('div', { className: props.className, 'data-account-extension': view.id }, view.tabs.length > 0
+        ? e('nav', { role: 'tablist', 'data-block': 'tabs' }, view.tabs.map((tab) => e('a', { key: tab.id, href: tab.href, role: 'tab', 'aria-selected': tab.active }, tab.label)))
+        : null, view.blocks.map((block, i) => e(Block, { key: i, block, props })));
+}

package/build/src/account_extensions/types.d.ts

@@ -0,0 +1,174 @@
+export interface AccountExtensionValue {
+    type: 'text' | 'money' | 'date' | 'badge' | 'number';
+    text: string;
+    tone?: 'neutral' | 'success' | 'warning' | 'danger';
+    iso?: string;
+    amount?: number;
+    currency?: string;
+    value?: number;
+}
+export interface AccountExtensionActionButton {
+    action: string;
+    target: string | null;
+    label: string;
+    tone: 'default' | 'danger';
+    sudo: boolean;
+    step: boolean;
+    href: string;
+    postHref: string;
+    apiHref: string;
+}
+export type AccountExtensionBlock = {
+    kind: 'notice';
+    tone: 'info' | 'success' | 'warning' | 'danger';
+    text: string;
+} | {
+    kind: 'keyValue';
+    title: string | null;
+    rows: Array<{
+        label: string;
+        value: AccountExtensionValue;
+    }>;
+    actions: AccountExtensionActionButton[];
+} | {
+    kind: 'list';
+    title: string | null;
+    empty: string;
+    items: Array<{
+        title: string;
+        subtitle: string | null;
+        meta: AccountExtensionValue[];
+        badge: AccountExtensionValue | null;
+        href: string | null;
+        external: boolean;
+        actions: AccountExtensionActionButton[];
+    }>;
+    nextHref: string | null;
+    nextCursor: string | null;
+} | {
+    kind: 'table';
+    title: string | null;
+    empty: string;
+    columns: Array<{
+        id: string;
+        label: string;
+    }>;
+    rows: Array<{
+        cells: AccountExtensionValue[];
+        actions: AccountExtensionActionButton[];
+    }>;
+    hasActions: boolean;
+    nextHref: string | null;
+    nextCursor: string | null;
+} | {
+    kind: 'meter';
+    label: string;
+    used: number;
+    limit: number | null;
+    percent: number | null;
+    text: string;
+    resetsAt: AccountExtensionValue | null;
+} | {
+    kind: 'actions';
+    items: AccountExtensionActionButton[];
+} | {
+    kind: 'link';
+    label: string;
+    href: string;
+    external: boolean;
+} | {
+    kind: 'toolPreview';
+    title: string;
+    tool: string | null;
+    subtitle: string | null;
+    args: Array<{
+        label: string;
+        value: AccountExtensionValue;
+    }>;
+    body: {
+        format: 'json' | 'text';
+        content: string;
+    } | null;
+    actions: AccountExtensionActionButton[];
+} | {
+    kind: 'component';
+    provider: string;
+    mountId: string;
+    scripts: Array<{
+        src: string;
+        integrity: string | null;
+        module: boolean;
+    }>;
+    propsJson: string;
+    props: Record<string, unknown>;
+    submit: AccountExtensionActionButton | null;
+    fallback: {
+        label: string;
+        href: string;
+        external: boolean;
+    } | null;
+};
+export interface AccountExtensionPageView {
+    id: string;
+    extension: string;
+    title: string;
+    href: string;
+    tabs: Array<{
+        id: string;
+        label: string;
+        href: string;
+        active: boolean;
+    }>;
+    blocks: AccountExtensionBlock[];
+}
+export interface AccountExtensionActionField {
+    name: string;
+    label: string;
+    kind: 'text' | 'select' | 'textarea';
+    required: boolean;
+    maxLength: number | null;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    value: string;
+}
+export interface AccountExtensionActionDefinition {
+    label: string;
+    tone: 'default' | 'danger';
+    confirm: string | null;
+    sudo: boolean;
+    fields: AccountExtensionActionField[];
+}
+export interface AccountExtensionPageResult {
+    page: AccountExtensionPageView;
+    actions: Record<string, AccountExtensionActionDefinition>;
+}
+export interface AccountNavEntry {
+    id: string;
+    label: string;
+    href: string;
+    active: boolean;
+    group: 'account' | 'billing' | 'ai' | 'content';
+    order: number;
+}
+export interface AccountExtensionsResult {
+    nav: AccountNavEntry[];
+    pages: Array<{
+        id: string;
+        label: string;
+        href: string;
+        order: number;
+        group: AccountNavEntry['group'];
+    }>;
+}
+export interface AccountExtensionActionInput {
+    target?: string | null;
+    fields?: Record<string, string>;
+}
+export interface AccountExtensionActionResult {
+    ok: true;
+    flash: string;
+    redirectTo: string | null;
+    external: boolean;
+}

package/build/src/account_extensions/types.js

@@ -0,0 +1 @@
+export {};

package/build/src/client/client.d.ts

@@ -1,3 +1,4 @@
+import type { AccountExtensionActionInput, AccountExtensionActionResult, AccountExtensionPageResult, AccountExtensionsResult } from '../account_extensions/types.js';
 import type { AcceptOrgInvitationResult, AccountAgentsResult, AccountAppsResult, AccountLoginMethodsResult, AccountMe, AccountMfaStatus, AccountOrgDetail, AccountOrgInvitationsResult, AccountOrgsResult, AccountPasskeysResult, AccountSecurityOverview, AccountSessionsResult, AccountTokensResult, ActivateOrgResult, AdminClient, AdminClientListResult, AdminOrgDetail, AdminOrgEntry, AdminOrgInvitation, AdminOrgListResult, AdminOverview, AdminUser, AdminUserListResult, AuditListParams, AuditListResult, ChangePasswordInput, CreateAccountOrgInput, CreateClientInput, CreatedAccountOrgResult, CreatedClientResult, CreatedOrgInvitationResult, CreatedPatResult, CreateOrgInput, CreateRoleInput, CreateTokenInput, CreateUserInput, DeactivateOrgResult, DeletedResult, EmailChangeResult, ImpersonationPanel, InviteOrgMemberInput, KeysRotateInput, KeysRotateResult, KeysStatus, LeaveOrgResult, MfaConfirmResult, MfaDisableResult, MfaEnrollResult, MfaRecoveryCodesResult, OkResult, PasskeyRegistrationOptions, PersonalAgentConnectionsParams, PersonalAgentConnectionsResult, PersonalAgentRegistryInput, PersonalAgentRegistryResult, PersonalAgentsOverview, RegenerateSecretResult, RemoveOrgMemberResult, RemovePasskeyResult, RequestEmailChangeInput, ResetPasswordResult, RevokeAllResult, RevokeAppResult, RevokeOrgInvitationResult, RevokeOthersResult, RevokeSessionResult, RevokeSessionsResult, RevokeTokenResult, RoleCatalogEntry, RoleListResult, SettingEntry, SettingListResult, UpdateClientInput, UpdateLoginMethodsResult, UpdateOrgInput, UpdateOrgMemberRoleResult, UpdateProfileInput, UpdateProfileResult, UpdateRoleInput, UpdateUserInput, UserLoginMethodsInput, UserSessionsResult } from './types.js';
 export declare class AuthkitClientError extends Error {
     readonly status: number;
@@ -194,6 +195,14 @@ declare class AuthkitClient {
             readonly removeMember: (orgId: string, accountId: string) => Promise<RemoveOrgMemberResult>;
             readonly acceptInvitation: (token: string) => Promise<AcceptOrgInvitationResult>;
         };
+        readonly extensions: {
+            readonly list: () => Promise<AccountExtensionsResult>;
+            readonly page: (pageId: string, query?: {
+                cursor?: string;
+                tab?: string;
+            }) => Promise<AccountExtensionPageResult>;
+            readonly action: (pageId: string, action: string, input?: AccountExtensionActionInput) => Promise<AccountExtensionActionResult>;
+        };
     };
 }
 export declare function createAuthkitClient(opts?: AuthkitClientOptions): AuthkitClient;

package/build/src/client/client.js

@@ -244,6 +244,11 @@ class AuthkitClient {
             removeMember: (orgId, accountId) => this.delete(this.a(`/orgs/${encodeURIComponent(orgId)}/members/${encodeURIComponent(accountId)}`)),
             acceptInvitation: (token) => this.post(this.a(`/orgs/invitations/${encodeURIComponent(token)}/accept`)),
         },
+        extensions: {
+            list: () => this.get(this.a('/extensions')),
+            page: (pageId, query) => this.get(this.a(`/x/${encodeURIComponent(pageId)}`), query),
+            action: (pageId, action, input = {}) => this.post(this.a(`/x/${encodeURIComponent(pageId)}/actions/${encodeURIComponent(action)}`), input),
+        },
     };
 }
 export function createAuthkitClient(opts) {

package/build/src/queries/keys.d.ts

@@ -50,6 +50,14 @@ export declare const authkitKeys: {
         readonly org: (id: string) => readonly ['authkit', 'account', 'orgs', string];
         readonly orgInvitations: () => readonly ['authkit', 'account', 'orgs', 'invitations'];
         readonly loginMethods: () => readonly ['authkit', 'account', 'login-methods'];
+        readonly extensions: () => readonly ['authkit', 'account', 'extensions'];
+        readonly extensionPage: (pageId: string, query?: {
+            cursor?: string;
+            tab?: string;
+        }) => readonly ['authkit', 'account', 'extensions', string, {
+            cursor?: string;
+            tab?: string;
+        }];
         readonly mutations: {
             readonly orgs: () => readonly ['authkit', 'account', 'orgs', 'mutation'];
             readonly orgCreate: () => readonly ['authkit', 'account', 'orgs', 'mutation', 'create'];

package/build/src/queries/keys.js

@@ -34,6 +34,8 @@ export const authkitKeys = {
         org: (id) => ['authkit', 'account', 'orgs', id],
         orgInvitations: () => ['authkit', 'account', 'orgs', 'invitations'],
         loginMethods: () => ['authkit', 'account', 'login-methods'],
+        extensions: () => ['authkit', 'account', 'extensions'],
+        extensionPage: (pageId, query) => ['authkit', 'account', 'extensions', pageId, query ?? {}],
         mutations: {
             orgs: () => ['authkit', 'account', 'orgs', 'mutation'],
             orgCreate: () => ['authkit', 'account', 'orgs', 'mutation', 'create'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonis-agora/authkit-react",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.3",
   "description": "Frontend ergonomics over AuthKit for AdonisJS + Inertia + React apps: a typed useAuth() hook, role-gating hooks and gating components.",
   "license": "MIT",
   "author": "dudousxd",