@segmentstream-cloud/app 0.3.2 → 0.5.0

package/README.md

@@ -2,7 +2,8 @@
 
 Sign-in, users, permissions, the ontology client and warehouse data access for
 SegmentStream workspace apps built with Next.js (App Router, version 16 or later) and
-React 19. The app's users sign in with an email code through Neon Auth (Managed
+React 19. The app's users sign in with an email code, or a sign-in link the first time,
+through Neon Auth (Managed
 Better Auth) on the workspace's Neon project; the workspace's ontology decides who may
 use the app and what they may do. The SDK wraps `@neondatabase/auth`, so the app never
 configures Neon Auth itself.
@@ -57,7 +58,7 @@ The route completes emailed sign-in links (`/api/auth/magic-link/verify`) itself
 verifies the token through Neon Auth without a callback, sets the session cookies on
 the app's domain and redirects to the link's `callbackURL` path. An expired, used or
 unknown link redirects to `/sign-in?error=sign_in_link_invalid`, where `<SignIn />` (or
-`useSignIn().linkInvalid`) offers a new code.
+`useSignIn().linkInvalid`) offers a new one.
 
 **`src/app/sign-in/page.tsx`** renders the sign-in form, and the root layout imports
 its stylesheet once. Apps with their own design system render their own form on
@@ -125,16 +126,16 @@ user in Server Functions and Route Handlers too; do not rely on the proxy alone.
 (no Tailwind). Every class starts with `ss-`; the `--ss-*` custom properties on
 `:root` set colours, radius and font.
 
-| Export                                 | Does                                                                               |
-| -------------------------------------- | ---------------------------------------------------------------------------------- |
-| `<SignIn />`                           | Email, then the six-digit code; resend after 30 seconds, errors and loading states |
-| `useSignIn()`                          | The same sign-in without markup, for the app's own form                            |
-| `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                   |
-| `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise          |
-| `<UserMenu />`                         | Name, email, roles and sign-out                                                    |
-| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session         |
-| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                               |
-| `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                    |
+| Export                                 | Does                                                                            |
+| -------------------------------------- | ------------------------------------------------------------------------------- |
+| `<SignIn />`                           | Email, then a six-digit code or a sign-in link; resend after 30 seconds, errors |
+| `useSignIn()`                          | The same sign-in without markup, for the app's own form                         |
+| `<SignedIn>`, `<SignedOut>`            | Render children by session state                                                |
+| `<Can permission="lead:changeStatus">` | Renders children when the user holds the permission; `fallback` otherwise       |
+| `<UserMenu />`                         | Name, email, roles and sign-out                                                 |
+| `useUser()`                            | `{ status, user, error }` from `/api/ontology/me`, loaded once per session      |
+| `usePermissions()`                     | `{ isLoading, roles, permissions, can(permission) }`                            |
+| `useSession()`, `signOut()`            | The Neon Auth session in the browser; sign-out from the browser                 |
 
 `<Can>` only hides controls: the ontology service checks every read and action. A
 Server Component may wrap server-rendered children in `<Can>`:
@@ -148,9 +149,17 @@ Server Component may wrap server-rendered children in `<Can>`:
 ### Your own sign-in form
 
 `useSignIn({ returnTo, error })` holds everything `<SignIn />` does, without markup: the
-steps, the 30-second resend hold, the six-digit check, error sentences, the return to
-`returnTo` after sign-in and the `not_invited` and `sign_in_link_invalid` states. Both
-options default to the page's query parameters. The workspace starter renders it with
+sign-in check, the steps, the 30-second resend hold, the six-digit check, error sentences
+and their codes, the return to `returnTo` after sign-in and the `not_invited` and
+`sign_in_link_invalid` states. Both options default to the page's query parameters.
+
+`submitEmail()` first asks the ontology's `POST /api/ontology/sign-in/check` whether the
+address may sign in. A member who has signed in with Neon Auth before gets a six-digit
+code (`step: "code"`). A first sign-in gets a sign-in link instead (`step: "link"`),
+because Neon Auth sends codes only to existing accounts and the link creates the
+account. An address the ontology refuses gets `errorCode: "not_invited"`, and nothing
+is sent. Without an ontology that answers the check (none, or one deployed with
+`@segmentstream-cloud/ontology` before 0.4), every address gets a code. The workspace starter renders it with
 Tailwind CSS and shadcn/ui in `src/components/sign-in-form.tsx`; `<SignIn />` stays for
 apps without Tailwind.
 
@@ -177,11 +186,22 @@ export function SignInForm() {
           onChange={(event) => signIn.setEmail(event.target.value)}
         />
         {signIn.error !== null && <p role="alert">{signIn.error}</p>}
-        <button disabled={signIn.pending !== null}>Send code</button>
+        <button disabled={signIn.pending !== null}>Continue</button>
       </form>
     );
   }
 
+  if (signIn.step === "link") {
+    return (
+      <p>
+        We sent a sign-in link to {signIn.email}. Open it to sign in.
+        <button type="button" onClick={() => void signIn.resend()} disabled={signIn.resendIn > 0}>
+          Resend link
+        </button>
+      </p>
+    );
+  }
+
   return (
     <form
       noValidate
@@ -206,19 +226,20 @@ export function SignInForm() {
 }
 ```
 
-| Field                                  | Means                                                                                  |
-| -------------------------------------- | -------------------------------------------------------------------------------------- |
-| `step`                                 | `email`, then `code` once a code is sent                                               |
-| `email`, `setEmail`, `code`, `setCode` | The field values; `submitEmail()` trims the address                                    |
-| `pending`                              | `send`, `verify`, `resend` or `sign-out` while a call runs; disable the form           |
-| `error`, `notice`                      | A sentence for the person, and a confirmation such as a resent code                    |
-| `resendIn`                             | Seconds until `resend()` may be offered; 0 when it may                                 |
-| `submitEmail()`, `submitCode(value?)`  | Send the code; verify `value` or `code`. A wrong code clears `code`; refocus the field |
-| `resend()`, `changeEmail()`            | Another code to the same address; back to the email step                               |
-| `signedIn`, `destination`              | A session already exists: offer a link to `destination`                                |
-| `notInvited`, `sessionEmail`           | The person is signed in as `sessionEmail` without an invitation                        |
-| `switchAccount()`                      | Signs out and returns to the email step                                                |
-| `linkInvalid`                          | An emailed sign-in link was expired or used: say so on the email step                  |
+| Field                                  | Means                                                                                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| `step`                                 | `email`, then `code` once a code is sent, or `link` once a sign-in link is sent       |
+| `email`, `setEmail`, `code`, `setCode` | The field values; `submitEmail()` trims the address                                   |
+| `pending`                              | `send`, `verify`, `resend` or `sign-out` while a call runs; disable the form          |
+| `error`, `notice`                      | A sentence for the person, and a confirmation such as a resent code                   |
+| `errorCode`, `noticeCode`              | Why the call failed (`not_invited`, `code_invalid`, …) and what was resent, to reword |
+| `resendIn`                             | Seconds until `resend()` may be offered; 0 when it may                                |
+| `submitEmail()`, `submitCode(value?)`  | Check, then send a code or link; verify `value` or `code`. A wrong code clears `code` |
+| `resend()`, `changeEmail()`            | Another code, or link, to the same address; back to the email step                    |
+| `signedIn`, `destination`              | A session already exists: offer a link to `destination`                               |
+| `notInvited`, `sessionEmail`           | The person is signed in as `sessionEmail` without an invitation                       |
+| `switchAccount()`                      | Signs out and returns to the email step                                               |
+| `linkInvalid`                          | An emailed sign-in link was expired or used: say so on the email step                 |
 
 The calls take values, not form events: call `submitEmail()` and `submitCode()` from the
 form's submit handler after `event.preventDefault()`. A second `submitCode()` while one
@@ -304,10 +325,9 @@ export default async function Page() {
 - Values arrive as JSON: safe integers as numbers, larger integers and decimals as strings,
   timestamps as ISO strings, records and arrays as JSON strings.
 
-`segmentstream.semantic` (governed metrics from semantic models) and
-`segmentstream.fetch(path)` (any SegmentStream API path) act as the signed-in
-SegmentStream member, so they need the legacy sign-in; under Neon Auth they throw
-`app_credential_missing`.
+`segmentstream.ontology.<entity>.aggregate(request)` uses the server-held workspace app
+credential and supports Neon Auth apps. Stored record operations use the ontology user token.
+`segmentstream.fetch(path)` still requires the legacy platform session.
 
 ## How requests are handled
 
@@ -366,7 +386,7 @@ Without `NEON_AUTH_BASE_URL`, 0.3 behaves exactly as 0.2, so existing apps keep
 working: members of the workspace's organization sign in with their SegmentStream
 account through `/api/segmentstream/[...path]/route.ts`
 (`export const { GET, POST } = segmentstream.handlers();`), the proxy redirects to
-SegmentStream, and `fetch`, `warehouse` and `semantic` act as the member. In that mode
+SegmentStream, and `fetch` acts as the member; warehouse queries and aggregates prefer the workspace app credential. In that mode
 `roles` and `permissions` are empty, `can()` is `false`, `authHandlers()` answers
 `404 neon_auth_not_configured`, and `segmentstream.ontology` sends the member's app
 token, which the ontology service accepts while workspaces move to Neon Auth. Keep the
@@ -378,6 +398,18 @@ Add the auth route, the sign-in page and the stylesheet import; keep the legacy
 `AppUser` gained `roles` and `permissions`. Under Neon Auth, people sign in again with
 an email code, and the ontology must have invited them.
 
+## Upgrading to 0.4
+
+`useSignIn().step` may now be `link`: render it, or a form written for 0.3 shows the code
+step after a link was sent. The `<SignIn />` button reads "Continue". Deploy the
+ontology with `@segmentstream-cloud/ontology` 0.4 or later to answer the sign-in check;
+until then every address gets a code, as in 0.3. `errorCode` and `noticeCode` let an
+app word messages in its own language without matching the English sentences.
+
 ## License
 
 Apache-2.0
+
+## Upgrading to 0.5
+
+Replace segmentstream.semantic with typed warehouse-backed entity aggregates. See [ontology aggregates](../../docs/ontology-aggregates.md). Warehouse-backed clients expose no record CRUD or actions.

package/dist/app.d.ts

@@ -1,5 +1,5 @@
 import type { Environment, SegmentStreamAppConfig } from "./config.js";
-import type { SemanticClient, WarehouseClient } from "./data.js";
+import type { WarehouseClient } from "./data.js";
 import type { SegmentStreamRouteHandlers } from "./handlers.js";
 import type { AuthRouteHandlers, CreateNeonAuth, SignOutOptions } from "./neon.js";
 import type { OntologyClient } from "./ontology.js";
@@ -44,8 +44,6 @@ export interface SegmentStreamApp<O = unknown> {
      * (`SEGMENTSTREAM_APP_CREDENTIAL`) when it is set, else the signed-in member's session.
      */
     readonly warehouse: WarehouseClient;
-    /** Governed metrics from the workspace's deployed semantic models. Server-only. Legacy sign-in only. */
-    readonly semantic: SemanticClient;
     /** The app's ontology service, `/api/ontology`, as the signed-in user. Server-only. */
     readonly ontology: OntologyClient<O>;
 }

package/dist/app.js

@@ -48,13 +48,12 @@ export function createApp(config, dependencies = {}) {
             getAccessToken: legacy.getAccessToken,
             fetch: data.fetch,
             warehouse: data.warehouse,
-            semantic: data.semantic,
             // The ontology service accepts SegmentStream app tokens while workspaces move to Neon Auth.
             ontology: createOntologyClient(createOntologyTransport({
                 fetch: fetchImplementation,
                 ontologyUrl: ontologyUrl === undefined ? undefined : new URL(ontologyUrl).origin,
                 credentials: { token: legacy.getAccessToken },
-            })),
+            }), data.aggregateTransport),
         };
     }
     const neon = createNeonSession({
@@ -82,8 +81,7 @@ export function createApp(config, dependencies = {}) {
         getAccessToken: async () => null,
         fetch: data.fetch,
         warehouse: data.warehouse,
-        semantic: data.semantic,
-        ontology: createOntologyClient(neon.ontologyTransport),
+        ontology: createOntologyClient(neon.ontologyTransport, data.aggregateTransport),
     };
 }
 /** Under Neon Auth the app has no SegmentStream session to call the API with. */
@@ -91,7 +89,7 @@ async function noSegmentStreamSession() {
     throw new SegmentStreamApiError({
         code: "app_credential_missing",
         status: 401,
-        detail: "Apps that sign in with Neon Auth have no SegmentStream session. Warehouse queries use the workspace app credential, SEGMENTSTREAM_APP_CREDENTIAL, which is not set; SegmentStream sets it on deploy. Other SegmentStream API calls are not available to these apps yet.",
+        detail: "Apps that sign in with Neon Auth have no SegmentStream session. Warehouse queries and ontology aggregates use the workspace app credential, SEGMENTSTREAM_APP_CREDENTIAL, which is not set; SegmentStream sets it on deploy. Other SegmentStream API calls are not available to these apps yet.",
     });
 }
 function notConfiguredHandlers() {

package/dist/data.d.ts

@@ -43,38 +43,39 @@ export interface WarehouseDryRun {
     readonly bytesProcessed: string | null;
     readonly maximumBytesBilled: string;
 }
-export interface SemanticQueryRequest {
-    readonly dimensions: readonly string[];
-    readonly measures: readonly string[];
-    readonly dateRange: {
+export interface AggregateRequest<Property extends string = string, Measure extends string = string, Temporal extends Property = Property> {
+    readonly dimensions: readonly Property[];
+    readonly measures: readonly Measure[];
+    readonly dateRange?: {
         readonly from: string;
         readonly to: string;
     };
+    readonly granularityOf?: Temporal;
     readonly granularity?: "day" | "week" | "month";
     readonly filters?: ReadonlyArray<{
-        readonly dimension: string;
+        readonly dimension: Property;
         readonly operator: "equals" | "in" | "isNull" | "isNotNull";
         readonly value?: string | number | boolean;
         readonly values?: ReadonlyArray<string | number | boolean>;
     }>;
     readonly orderBy?: ReadonlyArray<{
-        readonly measure?: string;
-        readonly dimension?: string;
+        readonly measure?: Measure;
+        readonly dimension?: Property;
         readonly direction: "asc" | "desc";
     }>;
     readonly limit?: number;
 }
-export interface SemanticField {
+export interface AggregateField {
     readonly name: string;
     readonly label: string;
     readonly type: string;
     readonly unit?: string;
     readonly format?: string;
 }
-export interface SemanticQueryResult<Row = Record<string, string | boolean | null>> {
+export interface AggregateResult<Row = Record<string, string | boolean | null>> {
     readonly deploymentId: string | null;
     readonly definitionDigest: string;
-    readonly fields: readonly SemanticField[];
+    readonly fields: readonly AggregateField[];
     readonly rows: Row[];
     readonly truncated: boolean;
     readonly execution: {
@@ -94,18 +95,6 @@ export interface WarehouseClient {
     /** Validates SQL and estimates bytes processed without running it. */
     readonly dryRun: (sql: string, options?: Pick<WarehouseQueryOptions, "params" | "maximumBytesBilled" | "signal">) => Promise<WarehouseDryRun>;
 }
-export interface SemanticClient {
-    readonly list: () => Promise<{
-        readonly deploymentId: string | null;
-        readonly models: readonly unknown[];
-    }>;
-    readonly get: (model: string) => Promise<{
-        readonly deploymentId: string | null;
-        readonly definitionDigest: string;
-        readonly model: unknown;
-    }>;
-    readonly query: <Row = Record<string, string | boolean | null>>(model: string, request: SemanticQueryRequest) => Promise<SemanticQueryResult<Row>>;
-}
 export interface DataClientDependencies {
     readonly config: ResolvedConfig;
     readonly fetch: Fetch;
@@ -122,5 +111,7 @@ export interface DataClientDependencies {
 export declare function createDataClient(dependencies: DataClientDependencies): {
     fetch: (path: string, init?: RequestInit) => Promise<Response>;
     warehouse: WarehouseClient;
-    semantic: SemanticClient;
+    aggregateTransport: {
+        fetch: (path: string, init: RequestInit) => Promise<Response>;
+    };
 };

package/dist/data.js

@@ -154,12 +154,14 @@ export function createDataClient(dependencies) {
             };
         },
     };
-    const semantic = {
-        list: () => call("GET", `${workspace}/semantic-models`),
-        get: (model) => call("GET", `${workspace}/semantic-models/${encodeURIComponent(model)}`),
-        query: (model, request) => call("POST", `${workspace}/semantic-models/${encodeURIComponent(model)}/query`, request),
+    const aggregateTransport = {
+        fetch: (path, init) => {
+            if (!/^\/[a-z][a-z0-9_]*\/aggregate$/.test(path))
+                throw new TypeError("Invalid aggregate path.");
+            return authorizedFetch(`${workspace}/entities${path}`, init, warehouseToken);
+        },
     };
-    return { fetch: apiFetch, warehouse, semantic };
+    return { fetch: apiFetch, warehouse, aggregateTransport };
 }
 function bytesLimit(value) {
     if (value === undefined) {

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export type { AuthenticationMethod, SegmentStreamApp } from "./app.js";
 export type { ApiIssue } from "./errors.js";
 export type { CurrentUser } from "./me.js";
 export type { AuthRouteHandler, AuthRouteHandlers, SignOutOptions } from "./neon.js";
-export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, OntologyClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
+export type { ActionCall, ActionOptions, ActionResponse, Change, Edit, EditKind, EntityClient, FieldFilter, GeneratedActions, HistoryEntry, HistoryOptions, HistoryPage, JsonRecord, JsonValue, ManyFilter, OntologyClient, AggregateEntityClient, OntologyPage, OntologyQuery, OrderBy, RequestOptions, UntypedOntologyClient, ValidationIssue, Where, } from "./ontology.js";
 export type { PermissionHolder } from "./permissions.js";
-export type { SemanticClient, SemanticField, SemanticQueryRequest, SemanticQueryResult, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
+export type { AggregateField, AggregateRequest, AggregateResult, WarehouseClient, WarehouseColumn, WarehouseDryRun, WarehouseQueryOptions, WarehouseReadOptions, WarehouseQueryResult, WarehouseRow, WarehouseValue, } from "./data.js";
 export type { ParameterType, QueryParameterValue, QueryParameters, TypedParameter, } from "./parameters.js";
 export type { SegmentStreamAppConfig } from "./config.js";
 export type { SegmentStreamRouteHandlers, RouteHandler } from "./handlers.js";

package/dist/ontology.d.ts

@@ -1,3 +1,4 @@
+import type { AggregateRequest, AggregateResult } from "./data.js";
 /**
  * The typed client for the app's ontology service, `/api/ontology`. The app imports its ontology as
  * types only (`import type ontology from "../../ontology"`) and passes `typeof ontology` to
@@ -185,18 +186,30 @@ type ResultOf<A> = A extends {
 type ActionClients<A> = {
     readonly [K in keyof A & string]: ActionCall<InputOf<A[K]>, ResultOf<A[K]>>;
 };
+type PropertiesOf<E> = E extends {
+    readonly properties: infer P;
+} ? P : never;
+type MeasuresOf<E> = E extends {
+    readonly measures: infer M;
+} ? keyof M & string : never;
+export interface AggregateEntityClient<Property extends string = string, Measure extends string = string, Temporal extends Property = Property> {
+    readonly aggregate: (request: AggregateRequest<Property, Measure, Temporal>, options?: RequestOptions) => Promise<AggregateResult>;
+}
+type ClientOf<E> = E extends {
+    readonly definition: {
+        readonly source: object;
+    };
+} ? AggregateEntityClient<keyof PropertiesOf<E> & string, MeasuresOf<E>> : EntityClient<RecordOf<E>, ActionClients<ActionsOf<E>>>;
 type TypedOntologyClient<O> = {
-    readonly [N in NameOf<EntitiesOf<O>>]: EntityClient<RecordOf<Extract<EntitiesOf<O>, {
-        readonly name: N;
-    }>>, ActionClients<ActionsOf<Extract<EntitiesOf<O>, {
+    readonly [N in NameOf<EntitiesOf<O>>]: ClientOf<Extract<EntitiesOf<O>, {
         readonly name: N;
-    }>>>>;
+    }>>;
 };
 /** A client for any entity, when the app passes no ontology type. */
 export type UntypedOntologyClient = {
     readonly [entity: string]: EntityClient<JsonRecord, {
         readonly [action: string]: ActionCall<JsonRecord, JsonValue>;
-    }>;
+    }> & AggregateEntityClient;
 };
 /**
  * `segmentstream.ontology`: one client per entity of `O`, the type of the app's ontology
@@ -211,7 +224,7 @@ export interface OntologyTransport {
  * Entities and actions exist only in the app's types, so the client resolves them by name when
  * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/changeStatus`.
  */
-export declare function createOntologyClient<O>(transport: OntologyTransport): OntologyClient<O>;
+export declare function createOntologyClient<O>(transport: OntologyTransport, aggregateTransport?: OntologyTransport): OntologyClient<O>;
 /** `find` sends the query as URL parameters: `where` as JSON, `orderBy` as `field:direction`. */
 export declare function findParameters(query: OntologyQuery<JsonRecord>): URLSearchParams;
 export {};

package/dist/ontology.js

@@ -19,7 +19,7 @@ const RESERVED = new Set([
  * Entities and actions exist only in the app's types, so the client resolves them by name when
  * they are used: `ontology.lead.actions.changeStatus(…)` posts to `lead/actions/changeStatus`.
  */
-export function createOntologyClient(transport) {
+export function createOntologyClient(transport, aggregateTransport) {
     const entities = new Map();
     return new Proxy(Object.create(null), {
         get(_target, property) {
@@ -28,7 +28,14 @@ export function createOntologyClient(transport) {
             }
             let client = entities.get(property);
             if (client === undefined) {
-                client = entityClient(property, transport);
+                client = {
+                    ...entityClient(property, transport),
+                    aggregate: (request, options = {}) => {
+                        if (!aggregateTransport)
+                            throw new TypeError("An aggregate transport is required.");
+                        return send(aggregateTransport, "POST", `/${property}/aggregate`, request, options.signal);
+                    },
+                };
                 entities.set(property, client);
             }
             return client;

package/dist/ui/index.d.ts

@@ -4,8 +4,8 @@ export { usePermissions, useSession, useUser } from "./hooks.js";
 export type { Permissions } from "./hooks.js";
 export { SignIn } from "./sign-in.js";
 export type { SignInProps } from "./sign-in.js";
-export { signInErrorMessage, useSignIn } from "./use-sign-in.js";
-export type { SignInController, SignInOptions } from "./use-sign-in.js";
+export { SIGN_IN_ERROR_MESSAGES, signInErrorCode, signInErrorMessage, useSignIn, } from "./use-sign-in.js";
+export type { SignInController, SignInErrorCode, SignInNoticeCode, SignInOptions, } from "./use-sign-in.js";
 export type { SessionState, SessionUser, UserState } from "./store.js";
 export { isAllowed } from "../permissions.js";
 export type { CurrentUser } from "../me.js";

package/dist/ui/index.js

@@ -5,6 +5,6 @@
 export { Can, SignedIn, SignedOut, UserMenu, signOut } from "./components.js";
 export { usePermissions, useSession, useUser } from "./hooks.js";
 export { SignIn } from "./sign-in.js";
-export { signInErrorMessage, useSignIn } from "./use-sign-in.js";
+export { SIGN_IN_ERROR_MESSAGES, signInErrorCode, signInErrorMessage, useSignIn, } from "./use-sign-in.js";
 export { isAllowed } from "../permissions.js";
 export { SegmentStreamApiError, NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";

package/dist/ui/sign-in-check.d.ts

@@ -0,0 +1,14 @@
+/** The ontology's sign-in check, which the deployment serves beside the app. */
+export declare const SIGN_IN_CHECK_PATH = "/api/ontology/sign-in/check";
+/**
+ * How an address signs in, or why it may not: `code` for a member with a Neon Auth account, `link`
+ * for a first sign-in, which the link's account creation needs; `not_invited`, `email_invalid` or
+ * `rate_limited` when the ontology refuses before any email is sent.
+ */
+export type SignInCheckOutcome = "code" | "link" | "not_invited" | "email_invalid" | "rate_limited";
+/**
+ * Asks the ontology how this address signs in, before any email is sent. An app without an
+ * ontology, an ontology deployed with an SDK before 0.4, an answer the SDK cannot read and a failed
+ * request all get `code`: the sign-in works as it did before the check existed.
+ */
+export declare function checkSignIn(email: string): Promise<SignInCheckOutcome>;

package/dist/ui/sign-in-check.js

@@ -0,0 +1,41 @@
+import { readJson } from "../errors.js";
+/** The ontology's sign-in check, which the deployment serves beside the app. */
+export const SIGN_IN_CHECK_PATH = "/api/ontology/sign-in/check";
+/**
+ * Asks the ontology how this address signs in, before any email is sent. An app without an
+ * ontology, an ontology deployed with an SDK before 0.4, an answer the SDK cannot read and a failed
+ * request all get `code`: the sign-in works as it did before the check existed.
+ */
+export async function checkSignIn(email) {
+    let response;
+    try {
+        response = await fetch(SIGN_IN_CHECK_PATH, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ email }),
+            credentials: "same-origin",
+            cache: "no-store",
+        });
+    }
+    catch {
+        return "code";
+    }
+    if (response.status === 429) {
+        return "rate_limited";
+    }
+    if (response.status === 400) {
+        return "email_invalid";
+    }
+    if (!response.ok) {
+        return "code";
+    }
+    const body = await readJson(response);
+    if (typeof body !== "object" || body === null) {
+        return "code";
+    }
+    const { allowed, method } = body;
+    if (allowed === false) {
+        return "not_invited";
+    }
+    return allowed === true && method === "link" ? "link" : "code";
+}

package/dist/ui/sign-in.d.ts

@@ -4,7 +4,7 @@ export interface SignInProps extends SignInOptions {
     readonly title?: string;
 }
 /**
- * Email code sign-in with Neon Auth in the SDK's neutral styles: `useSignIn()` with markup. Apps
+ * Email sign-in with Neon Auth in the SDK's neutral styles: `useSignIn()` with markup. Apps
  * with their own design system render `useSignIn()` themselves.
  */
 export declare function SignIn({ title, ...options }: SignInProps): import("react").JSX.Element;

package/dist/ui/sign-in.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useId, useRef } from "react";
 import { useSignIn } from "./use-sign-in.js";
 /**
- * Email code sign-in with Neon Auth in the SDK's neutral styles: `useSignIn()` with markup. Apps
+ * Email sign-in with Neon Auth in the SDK's neutral styles: `useSignIn()` with markup. Apps
  * with their own design system render `useSignIn()` themselves.
  */
 export function SignIn({ title = "Sign in", ...options }) {
@@ -24,10 +24,15 @@ export function SignIn({ title = "Sign in", ...options }) {
         return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: "You are signed in" }), _jsx("p", { className: "ss-text", children: sessionEmail === null ? "You already have a session." : `Signed in as ${sessionEmail}.` }), _jsxs("div", { className: "ss-actions", children: [_jsx("a", { className: "ss-button", href: destination, children: "Continue" }), _jsx("button", { type: "button", className: "ss-button ss-button--secondary", onClick: () => void switchAccount(), children: "Use another email" })] })] }));
     }
     if (step === "email") {
-        return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: title }), _jsxs("p", { className: "ss-text", children: ["We will email you a ", codeLength, "-digit code to sign in."] }), _jsxs("form", { className: "ss-form", onSubmit: (event) => {
+        return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: title }), _jsx("p", { className: "ss-text", children: "We will email you a code or a link to sign in." }), _jsxs("form", { className: "ss-form", onSubmit: (event) => {
                         event.preventDefault();
                         void submitEmail();
-                    }, noValidate: true, children: [linkInvalid && (_jsx("p", { className: "ss-notice", role: "status", children: "This sign-in link is not valid anymore. Enter your email to get a new code." })), _jsxs("div", { className: "ss-field", children: [_jsx("label", { className: "ss-label", htmlFor: `${ids}-email`, children: "Email" }), _jsx("input", { id: `${ids}-email`, className: "ss-input", type: "email", name: "email", autoComplete: "email", inputMode: "email", required: true, value: email, onChange: (event) => setEmail(event.target.value), disabled: pending !== null, "aria-invalid": error !== null, "aria-describedby": error === null ? undefined : errorId })] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), _jsx("button", { type: "submit", className: "ss-button", disabled: pending !== null, "aria-busy": pending === "send", children: pending === "send" ? "Sending code…" : "Send code" })] })] }));
+                    }, noValidate: true, children: [linkInvalid && (_jsx("p", { className: "ss-notice", role: "status", children: "This sign-in link is not valid anymore. Enter your email to get a new code." })), _jsxs("div", { className: "ss-field", children: [_jsx("label", { className: "ss-label", htmlFor: `${ids}-email`, children: "Email" }), _jsx("input", { id: `${ids}-email`, className: "ss-input", type: "email", name: "email", autoComplete: "email", inputMode: "email", required: true, value: email, onChange: (event) => setEmail(event.target.value), disabled: pending !== null, "aria-invalid": error !== null, "aria-describedby": error === null ? undefined : errorId })] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), _jsx("button", { type: "submit", className: "ss-button", disabled: pending !== null, "aria-busy": pending === "send", children: pending === "send" ? "Sending…" : "Continue" })] })] }));
+    }
+    const resendButton = (label) => (_jsx("button", { type: "button", className: "ss-link", onClick: () => void resend(), disabled: pending !== null || resendIn > 0, "aria-busy": pending === "resend", children: pending === "resend" ? "Sending…" : resendIn > 0 ? `${label} in ${resendIn} s` : label }));
+    const anotherEmail = (_jsx("button", { type: "button", className: "ss-link", onClick: changeEmail, disabled: pending !== null, children: "Use another email" }));
+    if (step === "link") {
+        return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: "Check your email" }), _jsxs("p", { className: "ss-text", children: ["We sent a sign-in link to ", _jsx("strong", { children: email }), ". Open it on this device to sign in."] }), error !== null && (_jsx("p", { className: "ss-error", role: "alert", children: error })), notice !== null && (_jsx("p", { className: "ss-notice", role: "status", children: notice })), _jsxs("div", { className: "ss-actions", children: [resendButton("Resend link"), anotherEmail] })] }));
     }
     return (_jsxs("section", { className: "ss-card ss-sign-in", "aria-labelledby": `${ids}-title`, children: [_jsx("h1", { id: `${ids}-title`, className: "ss-title", children: "Check your email" }), _jsxs("p", { className: "ss-text", children: ["Enter the ", codeLength, "-digit code we sent to ", _jsx("strong", { children: email }), "."] }), _jsxs("form", { className: "ss-form", onSubmit: (event) => {
                     event.preventDefault();
@@ -38,9 +43,5 @@ export function SignIn({ title = "Sign in", ...options }) {
                                     if (digits.length === codeLength) {
                                         void submitCode(digits);
                                     }
-                                }, disabled: pending === "verify", "aria-invalid": error !== null, "aria-describedby": error === null ? undefined : errorId })] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), notice !== null && (_jsx("p", { className: "ss-notice", role: "status", children: notice })), _jsx("button", { type: "submit", className: "ss-button", disabled: pending !== null, "aria-busy": pending === "verify", children: pending === "verify" ? "Signing in…" : "Sign in" })] }), _jsxs("div", { className: "ss-actions", children: [_jsx("button", { type: "button", className: "ss-link", onClick: () => void resend(), disabled: pending !== null || resendIn > 0, "aria-busy": pending === "resend", children: pending === "resend"
-                            ? "Sending…"
-                            : resendIn > 0
-                                ? `Resend code in ${resendIn} s`
-                                : "Resend code" }), _jsx("button", { type: "button", className: "ss-link", onClick: changeEmail, disabled: pending !== null, children: "Use another email" })] })] }));
+                                }, disabled: pending === "verify", "aria-invalid": error !== null, "aria-describedby": error === null ? undefined : errorId })] }), error !== null && (_jsx("p", { id: errorId, className: "ss-error", role: "alert", children: error })), notice !== null && (_jsx("p", { className: "ss-notice", role: "status", children: notice })), _jsx("button", { type: "submit", className: "ss-button", disabled: pending !== null, "aria-busy": pending === "verify", children: pending === "verify" ? "Signing in…" : "Sign in" })] }), _jsxs("div", { className: "ss-actions", children: [resendButton("Resend code"), anotherEmail] })] }));
 }

package/dist/ui/use-sign-in.d.ts

@@ -8,9 +8,23 @@ export interface SignInOptions {
      */
     readonly error?: string;
 }
-/** Email code sign-in for a form the app renders itself. The calls take values, not form events. */
+/**
+ * Why the last call failed. `not_invited`: the ontology allows no sign-in with this address, so no
+ * email was sent. Apps that show another language word their message from it.
+ */
+export type SignInErrorCode = "email_required" | "email_invalid" | "not_invited" | "code_incomplete" | "code_invalid" | "code_expired" | "too_many_attempts" | "rate_limited" | "unavailable" | "failed";
+/** What the last call confirmed: another code, or another sign-in link, was sent. */
+export type SignInNoticeCode = "code_resent" | "link_resent";
+/** The SDK's sentence for each {@link SignInErrorCode}. */
+export declare const SIGN_IN_ERROR_MESSAGES: Readonly<Record<SignInErrorCode, string>>;
+/** Email sign-in for a form the app renders itself. The calls take values, not form events. */
 export interface SignInController {
-    readonly step: "email" | "code";
+    /**
+     * `email`, then `code` for a member with a Neon Auth account, or `link` when a sign-in link was
+     * emailed instead: a first sign-in, whose link creates the account. The link step has nothing to
+     * submit; the person opens the link from the email.
+     */
+    readonly step: "email" | "code" | "link";
     readonly email: string;
     readonly setEmail: (value: string) => void;
     readonly code: string;
@@ -19,9 +33,13 @@ export interface SignInController {
     readonly pending: "send" | "verify" | "resend" | "sign-out" | null;
     /** A sentence for the person, from the last failed call. */
     readonly error: string | null;
+    /** Why the last call failed, for apps that word `error` themselves. */
+    readonly errorCode: SignInErrorCode | null;
     /** A confirmation, such as a new code having been sent. */
     readonly notice: string | null;
-    /** Seconds until another code may be requested; 0 when it may. */
+    /** What `notice` confirms, for apps that word it themselves. */
+    readonly noticeCode: SignInNoticeCode | null;
+    /** Seconds until another code or link may be requested; 0 when it may. */
     readonly resendIn: number;
     /** Digits in a code: 6. */
     readonly codeLength: number;
@@ -38,14 +56,18 @@ export interface SignInController {
     readonly linkInvalid: boolean;
     /** The signed-in address or name, for the not-invited state; null when signed out. */
     readonly sessionEmail: string | null;
-    /** Sends a code to `email` and moves to the code step. Call it from the form's submit handler. */
+    /**
+     * Asks the ontology whether `email` may sign in, then emails a code or a sign-in link and moves to
+     * `code` or `link`. An address the ontology refuses gets `not_invited`, and no email is sent. Call
+     * it from the form's submit handler.
+     */
     readonly submitEmail: () => Promise<void>;
     /**
      * Verifies `value`, or the current `code`, and opens `destination`. A wrong code clears `code`;
      * a second call while one is verifying is ignored, so the last digit and Enter may both submit.
      */
     readonly submitCode: (value?: string) => Promise<void>;
-    /** Sends another code to the same address. */
+    /** Sends another code, or another link on the link step, to the same address. */
     readonly resend: () => Promise<void>;
     /** Returns to the email step. */
     readonly changeEmail: () => void;
@@ -53,11 +75,15 @@ export interface SignInController {
     readonly switchAccount: () => Promise<void>;
 }
 /**
- * Email code sign-in with Neon Auth, without markup: the email address, then the six-digit code
- * sent to it. New addresses get an account on first sign-in; whether they may use the app is the
- * ontology's decision, which `requireUser()` reports as `not_invited`. `<SignIn />` renders it with
- * the SDK's own styles; apps with their own design system render the controller themselves.
+ * Email sign-in with Neon Auth, without markup. The ontology first says whether the address may
+ * sign in (`POST /api/ontology/sign-in/check`): a member with a Neon Auth account gets a six-digit
+ * code, a first sign-in gets a sign-in link, which creates the account, and an address the ontology
+ * refuses gets `not_invited` without an email. Without an ontology to ask, every address gets a
+ * code. `<SignIn />` renders it with the SDK's own styles; apps with their own design system render
+ * the controller themselves.
  */
 export declare function useSignIn({ returnTo, error: reason }?: SignInOptions): SignInController;
+/** Why a Neon Auth (Better Auth) call failed. */
+export declare function signInErrorCode(error: unknown): SignInErrorCode;
 /** A sentence for a Neon Auth (Better Auth) failure. */
 export declare function signInErrorMessage(error: unknown): string;

package/dist/ui/use-sign-in.js

@@ -4,21 +4,47 @@ import { NOT_INVITED, SIGN_IN_LINK_INVALID } from "../errors.js";
 import { safeReturnTo } from "../return-to.js";
 import { useSession } from "./hooks.js";
 import { navigate } from "./navigation.js";
+import { checkSignIn } from "./sign-in-check.js";
 import { authClient, clearSession, refreshSession } from "./store.js";
-/** Seconds before another code may be requested. */
+/** Seconds before another code or link may be requested. */
 const RESEND_AFTER_SECONDS = 30;
 const CODE_LENGTH = 6;
+/** The SDK's sentence for each {@link SignInErrorCode}. */
+export const SIGN_IN_ERROR_MESSAGES = {
+    email_required: "Enter your email address.",
+    email_invalid: "Enter a valid email address.",
+    not_invited: "This app has not invited this address. Check it, or ask your administrator for an invitation.",
+    code_incomplete: `Enter the ${CODE_LENGTH}-digit code from the email.`,
+    code_invalid: "That code is not right. Check the email and try again.",
+    code_expired: "That code has expired. Send a new one.",
+    too_many_attempts: "Too many wrong codes. Send a new code.",
+    rate_limited: "Too many requests. Wait a minute, then try again.",
+    unavailable: "Sign-in is unavailable right now. Try again in a moment.",
+    failed: "Sign-in failed. Try again.",
+};
 const noSubscription = () => () => { };
 /** The page's own query string; empty during server rendering. */
 function useSearchParameter(name) {
     const search = useSyncExternalStore(noSubscription, () => window.location.search, () => "");
     return new URLSearchParams(search).get(name);
 }
+function noticeFor(notice, email) {
+    switch (notice) {
+        case "code_resent":
+            return `We sent a new code to ${email}.`;
+        case "link_resent":
+            return `We sent a new sign-in link to ${email}.`;
+        case null:
+            return null;
+    }
+}
 /**
- * Email code sign-in with Neon Auth, without markup: the email address, then the six-digit code
- * sent to it. New addresses get an account on first sign-in; whether they may use the app is the
- * ontology's decision, which `requireUser()` reports as `not_invited`. `<SignIn />` renders it with
- * the SDK's own styles; apps with their own design system render the controller themselves.
+ * Email sign-in with Neon Auth, without markup. The ontology first says whether the address may
+ * sign in (`POST /api/ontology/sign-in/check`): a member with a Neon Auth account gets a six-digit
+ * code, a first sign-in gets a sign-in link, which creates the account, and an address the ontology
+ * refuses gets `not_invited` without an email. Without an ontology to ask, every address gets a
+ * code. `<SignIn />` renders it with the SDK's own styles; apps with their own design system render
+ * the controller themselves.
  */
 export function useSignIn({ returnTo, error: reason } = {}) {
     const session = useSession();
@@ -28,8 +54,8 @@ export function useSignIn({ returnTo, error: reason } = {}) {
     const [email, setEmail] = useState("");
     const [code, setCode] = useState("");
     const [pending, setPending] = useState(null);
-    const [error, setError] = useState(null);
-    const [notice, setNotice] = useState(null);
+    const [errorCode, setErrorCode] = useState(null);
+    const [noticeCode, setNoticeCode] = useState(null);
     const [resendIn, setResendIn] = useState(0);
     const [switchingAccount, setSwitchingAccount] = useState(false);
     const verifying = useRef(false);
@@ -49,28 +75,44 @@ export function useSignIn({ returnTo, error: reason } = {}) {
             }
         }, 1000);
     }
-    async function sendCode(address) {
-        const result = await attempt(() => authClient().emailOtp.sendVerificationOtp({ email: address, type: "sign-in" }));
+    function clearMessages() {
+        setErrorCode(null);
+        setNoticeCode(null);
+    }
+    /** Runs a Neon Auth call that emails the person; on success it holds the next one back. */
+    async function send(call) {
+        const result = await attempt(call);
         if (result !== null) {
-            setError(signInErrorMessage(result));
+            setErrorCode(signInErrorCode(result));
             return false;
         }
         holdResend();
         return true;
     }
+    function sendCode(address) {
+        return send(() => authClient().emailOtp.sendVerificationOtp({ email: address, type: "sign-in" }));
+    }
+    function sendLink(address) {
+        // Neon Auth checks the callback against the app's trusted origins, so it is absolute.
+        const callbackURL = new URL(destination, window.location.origin).href;
+        return send(() => authClient().signIn.magicLink({ email: address, callbackURL }));
+    }
     async function submitEmail() {
         const address = email.trim();
         if (address === "") {
-            setError("Enter your email address.");
+            setErrorCode("email_required");
             return;
         }
         setPending("send");
-        setError(null);
-        setNotice(null);
-        if (await sendCode(address)) {
+        clearMessages();
+        const outcome = await checkSignIn(address);
+        if (outcome !== "code" && outcome !== "link") {
+            setErrorCode(outcome);
+        }
+        else if (await (outcome === "code" ? sendCode(address) : sendLink(address))) {
             setEmail(address);
             setCode("");
-            setStep("code");
+            setStep(outcome);
         }
         setPending(null);
     }
@@ -80,17 +122,16 @@ export function useSignIn({ returnTo, error: reason } = {}) {
             return;
         }
         if (!new RegExp(`^[0-9]{${CODE_LENGTH}}$`).test(value)) {
-            setError(`Enter the ${CODE_LENGTH}-digit code from the email.`);
+            setErrorCode("code_incomplete");
             return;
         }
         verifying.current = true;
         setPending("verify");
-        setError(null);
-        setNotice(null);
+        clearMessages();
         const result = await attempt(() => authClient().signIn.emailOtp({ email, otp: value }));
         if (result !== null) {
             verifying.current = false;
-            setError(signInErrorMessage(result));
+            setErrorCode(signInErrorCode(result));
             setCode("");
             setPending(null);
             return;
@@ -99,23 +140,26 @@ export function useSignIn({ returnTo, error: reason } = {}) {
     }
     async function resend() {
         setPending("resend");
-        setError(null);
-        setNotice(null);
-        if (await sendCode(email)) {
+        clearMessages();
+        if (step === "link") {
+            if (await sendLink(email)) {
+                setNoticeCode("link_resent");
+            }
+        }
+        else if (await sendCode(email)) {
             setCode("");
-            setNotice(`We sent a new code to ${email}.`);
+            setNoticeCode("code_resent");
         }
         setPending(null);
     }
     function changeEmail() {
         setStep("email");
         setCode("");
-        setError(null);
-        setNotice(null);
+        clearMessages();
     }
     async function switchAccount() {
         setPending("sign-out");
-        setError(null);
+        setErrorCode(null);
         await attempt(() => authClient().signOut());
         clearSession();
         await refreshSession();
@@ -130,8 +174,10 @@ export function useSignIn({ returnTo, error: reason } = {}) {
         code,
         setCode,
         pending,
-        error,
-        notice,
+        error: errorCode === null ? null : SIGN_IN_ERROR_MESSAGES[errorCode],
+        errorCode,
+        notice: noticeFor(noticeCode, email),
+        noticeCode,
         resendIn,
         codeLength: CODE_LENGTH,
         destination,
@@ -156,8 +202,8 @@ async function attempt(call) {
         return error ?? new Error("Sign-in failed.");
     }
 }
-/** A sentence for a Neon Auth (Better Auth) failure. */
-export function signInErrorMessage(error) {
+/** Why a Neon Auth (Better Auth) call failed. */
+export function signInErrorCode(error) {
     const details = typeof error === "object" && error !== null ? error : {};
     const status = typeof details.status === "number" ? details.status : undefined;
     const text = [details.code, details.message]
@@ -165,22 +211,26 @@ export function signInErrorMessage(error) {
         .join(" ")
         .toLowerCase();
     if (status === 429 || text.includes("rate limit") || text.includes("too many requests")) {
-        return "Too many requests. Wait a minute, then try again.";
+        return "rate_limited";
     }
     if (text.includes("too many attempts") || text.includes("too_many_attempts")) {
-        return "Too many wrong codes. Send a new code.";
+        return "too_many_attempts";
     }
     if (text.includes("expired")) {
-        return "That code has expired. Send a new one.";
+        return "code_expired";
     }
     if (text.includes("otp") || text.includes("code")) {
-        return "That code is not right. Check the email and try again.";
+        return "code_invalid";
     }
     if (text.includes("email")) {
-        return "Enter a valid email address.";
+        return "email_invalid";
     }
     if (status === undefined || status >= 500 || text.includes("network")) {
-        return "Sign-in is unavailable right now. Try again in a moment.";
+        return "unavailable";
     }
-    return "Sign-in failed. Try again.";
+    return "failed";
+}
+/** A sentence for a Neon Auth (Better Auth) failure. */
+export function signInErrorMessage(error) {
+    return SIGN_IN_ERROR_MESSAGES[signInErrorCode(error)];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/app",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Sign-in, users, permissions, the ontology client and warehouse data access for SegmentStream workspace apps built with Next.js.",
   "license": "Apache-2.0",
   "author": "SegmentStream",