@nauticana/sail 1.1.27 → 1.1.29

package/README.md

@@ -2,7 +2,7 @@
 
 A shared Angular component library for building CRUD-based admin frontends. Provides table management, form handling, navigation, authentication, two-factor authentication, and trusted device management — all driven by metadata from a [keel](https://github.com/nauticana/keel) Go backend.
 
-> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.18 adopts keel v1.2.58 (refresh-token rotation, `/public/logout`, setup intents, the realtime hub), the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
+> **Compatibility:** sail and keel are versioned in lock-step. The current line is **sail v1.1.x ↔ keel v1.2.x**; sail v1.1.29 adopts keel v1.2.94 (signup: confirmation signs in, partner setup, sign-in hand-off code), sail v1.1.28 adopts keel v1.2.93 (absolute `return` for the OAuth hand-off), sail v1.1.18 adopts keel v1.2.58 (refresh-token rotation, `/public/logout`, setup intents, the realtime hub), the agency components in sail v1.1.14 require keel v1.2.41 (sail v1.1.9 needs keel v1.2.16 for the OAuth-connect layer). Earlier lines: **sail v0.5.x ↔ keel v0.5.x**, **sail v0.6.x / v0.7.x ↔ keel v0.7.x**, **sail v0.8.x ↔ keel v0.8.x**, **sail v0.9.x ↔ keel v0.9.x**. Newer sail releases extend the contract — older keel servers reject unknown endpoints with HTTP 404 / 400. The v0.8.x line additionally ships the `table_action` framework (per-table custom buttons surfaced in `TableList` / `TableSearch` / `TableEdit` / `TableDetail`); see the [Migrating to v0.7.0 §5 — TableAction](#migrating-to-v070--payout-user-payment-methods-table-actions) section for the seed shape (basis `table_action` + `authorization_object` + `authorization_object_action` rows) and the [keel/README Table Actions](https://github.com/nauticana/keel#table-actions) section for backend wiring via `handler.WrapTableAction`.
 
 **Recent additions:** `BaseAuthService.acceptToken(jwt)` — adopt an externally-minted JWT (registration / SSO-handoff flows) and run the full post-login sequence (store under the canonical `jwt` key, load appdata, init routes); apps must use this instead of writing `localStorage` directly. `BaseRestService.analytic<T>(endpoint, params?)` — GET a keel `analytic/<endpoint>` report and return its rows. `passwordPolicyValidator` + `BaseAuthService.ensurePasswordPolicy()` — validate passwords against keel's policy (via `SailGuiConfig.passwordPolicyUrl`); see Configuration reference.
 
@@ -315,11 +315,12 @@ interface SailGuiConfig {
 
 ### Password-policy validation
 
-**OAuth sign-in hand-off (v1.1.27, keel v1.2.89).** When the login page is opened with
-`?return=<authorize URL>` and both `oauthServerUrl` and `allowedReturnHosts` are set,
-`completeLogin` posts `{"return": <raw value>}` with the bearer JWT to
+**OAuth sign-in hand-off (v1.1.28, keel v1.2.93).** When the login page is opened with
+`?return=<absolute authorize URL>` and both `oauthServerUrl` and `allowedReturnHosts` are set,
+sail posts `{"return": <raw value>}` with the bearer JWT to
 `{oauthServerUrl}/oauth/session/handoff` and then leaves the SPA with a full navigation to the
-`redirect` keel answers. keel sets the authorization server's own HttpOnly cookie while
+`redirect` keel answers. This runs after a sign-in, and from `loadStoredSession()` when a user
+who is already signed in opens a `/login` route; a 401 rotates the refresh token once and retries. keel sets the authorization server's own HttpOnly cookie while
 redeeming that URL; sail does not opt into cross-origin cookies or send a CSRF token. A
 `return` whose host is not in `allowedReturnHosts`, or a `redirect` outside `oauthServerUrl`'s
 origin, is not followed. Failures set `BaseAuthService.sessionHandoffError` (rendered by
@@ -345,6 +346,10 @@ Omit the URL to skip client-side policy checks. The server stays the authoritati
 | `POST /public/otp/resend` | Re-issue OTP for an existing `otpToken` |
 | `POST /public/2fa/verify` | Login-time TOTP verification (uses `loginToken`) |
 | `POST /public/2fa/backup-verify` | Login-time backup-code verification |
+| `POST /public/register` | Start a signup from a `PartnerRegistration`; emails the confirmation code |
+| `POST /public/register/confirm` | Confirm `?email=&code=`; answers session tokens and the partner result (`confirmRegister`) |
+| `POST /public/register/exchange` | Trade a single-use hand-off `{code}` for a session (`exchangeHandoff`) |
+| `POST /api/register/partner` | Create the signed-in user's partner from a `PartnerSetup` (`createPartner`) |
 | `POST /public/token/refresh` | Rotate `{refreshToken}` → new `{token, refreshToken}`; 401 ends the session |
 | `POST /public/logout` | Revoke `{refreshToken}` (called by `BaseAuthService.logout()`) |
 | `GET /public/ws` | keel realtime hub handshake (`RealtimeService`; JWT via `?token=`) |
@@ -511,7 +516,9 @@ metadata: {
 
 ### Registration → checkout flow
 
-The registration confirmation (`ConfirmRegisterComponent`) already handles the payment redirect. When the backend returns `paymentRequired: true`, the user is sent to `resp.paymentUrl` (Stripe Checkout) automatically. No extra wiring needed — just select a paid plan during registration.
+`BaseAuthService.confirmRegister(email, code)` signs the user in from the tokens keel answers (keel v1.2.94), so no separate login follows. `ConfirmRegisterComponent` then sends the user to `resp.paymentUrl` when the backend returns `paymentRequired: true` with one; otherwise the post-login navigation applies.
+
+A two-step signup registers the account alone (a `PartnerRegistration` without partner fields), then calls `createPartner(setup)` once signed in. It posts keel's `PartnerSetup` — application fields ride in `extra` — rotates the refresh token so the session carries the new partner, reloads appdata and routes, and emits `PartnerCreated`. When `paymentRequired` comes without a `paymentUrl`, the application's billing page opens the checkout. `exchangeHandoff(code)` completes a sign-in that arrived by redirect with keel's single-use code, including the 2FA step.
 
 ### `BaseAsync`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nauticana/sail",
-  "version": "1.1.27",
+  "version": "1.1.29",
   "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing, payout onboarding.",
   "main": "src/index.ts",
   "exports": {

package/src/component/login/confirm_register_component.ts

@@ -1,7 +1,7 @@
 import { ChangeDetectionStrategy, Component, inject, OnInit, ViewEncapsulation } from '@angular/core';
 import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
 import { BaseAuthService } from '../../service/auth.service';
-import { ActivatedRoute, Router, RouterLink } from '@angular/router';
+import { ActivatedRoute, RouterLink } from '@angular/router';
 import { MatButtonModule } from '@angular/material/button';
 import { MatFormFieldModule } from '@angular/material/form-field';
 import { MatInputModule } from '@angular/material/input';
@@ -24,7 +24,6 @@ import { BaseAsync } from '../abstract/base_async';
 export class ConfirmRegisterComponent extends BaseAsync implements OnInit {
   private auth = inject(BaseAuthService);
   private fb = inject(FormBuilder);
-  private router = inject(Router);
   private route = inject(ActivatedRoute);
   protected readonly guiConfig: SailGuiConfig = inject(SAIL_GUI_CONFIG, {optional: true}) ?? DEFAULT_CONFIG;
 
@@ -49,15 +48,11 @@ export class ConfirmRegisterComponent extends BaseAsync implements OnInit {
       this.auth.confirmRegister(email!, code!),
       (resp) => {
         this.successMessage.set('Registration confirmed.');
+        // confirmRegister signed the user in and owns navigation; only a paid
+        // plan's checkout leaves the SPA (window.location: it is cross-origin).
         if (resp?.paymentRequired && resp.paymentUrl) {
-          // Paid plan: go straight to payment. Subscription is 'P' until paid.
-          // Using window.location (not router) so absolute / cross-origin
-          // payment URLs also work.
           window.location.href = resp.paymentUrl;
-          return;
         }
-        // Free plan: land on login.
-        this.router.navigate(['/login/local']);
       },
       'Confirmation failed. Please try again.',
     );

package/src/component/login/register_component.ts

@@ -159,22 +159,22 @@ export class RegisterComponent implements OnInit {
     this.registerError.set('');
     const formValue = this.registerForm.getRawValue();
     const partnerReg: PartnerRegistration = {
-      FirstName: formValue.FirstName!,
-      LastName: formValue.LastName!,
-      UserName: formValue.UserName!,
-      Email: formValue.Email!,
-      Password: formValue.Password!,
-      PartnerCaption: formValue.PartnerCaption!,
-      Address: formValue.Address!,
-      City: formValue.City!,
-      State: formValue.State!,
-      Zipcode: formValue.Zipcode!,
-      Country: formValue.Country!,
-      Phone: formValue.Phone!,
-      DomainURL: formValue.DomainURL!,
-      Latitude: formValue.Latitude,
-      Longitude: formValue.Longitude,
-      PlanID: formValue.PlanID!,
+      firstName: formValue.FirstName!,
+      lastName: formValue.LastName!,
+      userName: formValue.UserName!,
+      email: formValue.Email!,
+      password: formValue.Password!,
+      partnerCaption: formValue.PartnerCaption!,
+      address: formValue.Address!,
+      city: formValue.City!,
+      state: formValue.State!,
+      zipcode: formValue.Zipcode!,
+      country: formValue.Country!,
+      phone: formValue.Phone!,
+      domainUrl: formValue.DomainURL!,
+      latitude: formValue.Latitude ?? undefined,
+      longitude: formValue.Longitude ?? undefined,
+      planId: formValue.PlanID!,
     };
     this.auth.register(partnerReg).subscribe({
       // Pass the email along so the confirm page pre-fills it.

package/src/model/appdata.ts

@@ -198,24 +198,46 @@ export interface TrustedDevice {
   created_at:   string;
 }
 
-export interface PartnerRegistration {
-	FirstName:            string;
-	LastName:             string;
-	UserName:             string;
-	Email:                string;
-	Password:             string;
-	PartnerCaption:       string;
-	Address:              string;
-	City:                 string;
-	State:                string;
-	Zipcode:              string;
-	Country:              string;
-	Phone:                string;
-	// null when geocoding is disabled or the address wasn't verified.
-	Latitude:             number | null;
-	Longitude:            number | null;
-	DomainURL:            string;
-	PlanID:               string;
+// Mirrors keel `user.AccountRegistration`.
+export interface AccountRegistration {
+	firstName: string;
+	lastName:  string;
+	userName:  string;
+	email:     string;
+	password:  string;
+}
+
+// Mirrors keel `user.PartnerSetup`. `extra` carries the application's own fields.
+export interface PartnerSetup<TExtra = unknown> {
+	partnerCaption: string;
+	address:        string;
+	city:           string;
+	state:          string;
+	zipcode:        string;
+	country:        string;
+	phone:          string;
+	latitude?:      number;
+	longitude?:     number;
+	domainUrl:      string;
+	planId:         string;
+	// Chosen offer (PERIOD_TYPE codes); none selects the plan's cheapest.
+	billingCycle?:  string;
+	termType?:      string;
+	termCount?:     number;
+	extra?:         TExtra;
+}
+
+// Mirrors keel `user.PartnerRegistration`. Without partner fields only the
+// account is created and the partner follows through `createPartner`.
+export type PartnerRegistration<TExtra = unknown> = AccountRegistration & Partial<PartnerSetup<TExtra>>;
+
+// Mirrors keel `user.PartnerCreated`. `paymentRequired` without a `paymentUrl`
+// means the application's billing page opens the checkout.
+export interface PartnerCreated {
+	partnerId:       number;
+	planId:          string;
+	paymentRequired: boolean;
+	paymentUrl?:     string;
 }
 
 // One purchasable offer for a plan — a (billing cycle × commitment term) row of
@@ -261,15 +283,13 @@ export interface PublicPlan {
 	trialDays?:      number;
 }
 
-// ConfirmRegisterResponse — shape returned by POST /public/confirm/register.
-// When paymentRequired is true the UI should redirect the user to paymentUrl
-// before letting them log in.
-export interface ConfirmRegisterResponse {
-	status:          string;
-	partnerId:       number;
-	planId:          string;
-	paymentRequired: boolean;
-	paymentUrl?:     string;
+// ConfirmRegisterResponse — shape returned by POST /public/register/confirm:
+// the new session's tokens, plus the partner result when the registration had one.
+export interface ConfirmRegisterResponse extends TokenPair {
+	status:           string;
+	planId?:          string;
+	paymentRequired?: boolean;
+	paymentUrl?:      string;
 }
 
 // ── Billing / Payment types ──

package/src/service/auth.service.ts

@@ -2,7 +2,7 @@ import { Injectable, WritableSignal, inject, signal } from '@angular/core';
 import { HttpErrorResponse, HttpParams } from '@angular/common/http';
 import { filter, finalize, map, mergeMap, shareReplay, take, tap } from 'rxjs/operators';
 import { PasswordRules } from '../util/password_policy';
-import { ApplicationData, ConfirmRegisterResponse, DictionaryPath, LoginResponse2FA, PartnerRegistration, RestReport, TableDefinition, TokenPair, TrustedDevice, TwoFactorSetupResponse, TwoFactorVerifyRequest, TwoFactorVerifyResponse } from '../model/appdata';
+import { ApplicationData, ConfirmRegisterResponse, DictionaryPath, LoginResponse2FA, PartnerCreated, PartnerRegistration, PartnerSetup, RestReport, TableDefinition, TokenPair, TrustedDevice, TwoFactorSetupResponse, TwoFactorVerifyRequest, TwoFactorVerifyResponse } from '../model/appdata';
 import {
   LoginResponseSocial,
   OtpRequest, OtpResendRequest, OtpResponse, OtpVerifyRequest, OtpVerifyResponse,
@@ -25,7 +25,7 @@ export class RefreshSupersededError extends Error {
   constructor() { super('session changed during refresh'); this.name = 'RefreshSupersededError'; }
 }
 
-function handoffErrorMessage(status: number): string {
+function handoffErrorMessage(status: number | undefined): string {
   if (status === 400) return 'This sign-in link is not valid. Start again from the application you were connecting.';
   if (status === 401) return 'Your session was not accepted. Please sign in again.';
   return 'Could not complete sign-in. Please try again.';
@@ -90,6 +90,8 @@ export abstract class BaseAuthService extends BaseRestService {
   protected get registerUrl()              { return this.url(RestURL.registerURL); }
   protected get chpassUrl()                { return this.url(RestURL.chpassURL); }
   protected get confirmRegisterUrl()       { return this.url(RestURL.confirmRegisterURL); }
+  protected get registerExchangeUrl()      { return this.url(RestURL.registerExchangeURL); }
+  protected get registerPartnerUrl()       { return this.url(RestURL.registerPartnerURL); }
   protected get confirmChpassUrl()         { return this.url(RestURL.confirmChpassURL); }
   protected get loginGoogleUrl()           { return this.url(RestURL.loginGoogleURL); }
   protected get twoFactorSetupUrl()        { return this.url(RestURL.twoFactorSetupURL); }
@@ -219,25 +221,37 @@ export abstract class BaseAuthService extends BaseRestService {
     this.isLoggedIn.set(true);
     this.sessionHandoffError.set(null);
     resetAuthCircuit(); // a new session must not inherit a prior session's open circuit
-    const ret = this.validatedReturnUrl();
-    const oauthServer = this.oauthServerBase();
-    if (ret && oauthServer) {
-      this.handOffSession(oauthServer, ret, token);
-      return;
-    }
+    if (this.startHandoff()) return;
     this.loadAppData();
     this.initRoutes();
   }
 
+  /** Hands the session to the OAuth authorization server when the page carries an
+   * allowed `?return=` and oauthServerUrl is set; false when there is nothing to hand off. */
+  private startHandoff(): boolean {
+    const ret = this.validatedReturnUrl();
+    const oauthServer = this.oauthServerBase();
+    if (!ret || !oauthServer) return false;
+    this.handOffSession(oauthServer, ret);
+    return true;
+  }
+
   /** Exchange the bearer session for the authorization server's own cookie session
    * (keel POST /oauth/session/handoff), then leave the SPA for the URL it returns.
-   * Any failure stays on the login page; the browser is never sent elsewhere. */
-  private handOffSession(oauthServer: string, ret: string, token: string): void {
-    this.http.post<{ data?: { redirect?: unknown } }>(
+   * A 401 rotates the refresh token once and retries. Any failure stays on the
+   * login page; the browser is never sent elsewhere. */
+  private handOffSession(oauthServer: string, ret: string): void {
+    const mint = (token: string) => this.http.post<{ data?: { redirect?: unknown } }>(
         oauthServer + '/oauth/session/handoff',
         { return: ret },
         { headers: { Authorization: `Bearer ${token}` } },
-    ).pipe(take(1)).subscribe({
+    );
+    mint(this.token ?? '').pipe(
+      catchError((err: HttpErrorResponse) => err.status === 401 && localStorage.getItem('refreshToken')
+        ? this.refreshSession().pipe(mergeMap(mint))
+        : throwError(() => err)),
+      take(1),
+    ).subscribe({
       next: (res) => {
         const redirect = res?.data?.redirect;
         if (typeof redirect !== 'string' || !sameOrigin(redirect, oauthServer)) {
@@ -247,9 +261,9 @@ export abstract class BaseAuthService extends BaseRestService {
         }
         window.location.assign(redirect);
       },
-      error: (err: HttpErrorResponse) => {
+      error: (err: unknown) => {
         console.error('Session handoff failed:', err);
-        this.sessionHandoffError.set(handoffErrorMessage(err.status));
+        this.sessionHandoffError.set(handoffErrorMessage((err as { status?: number } | null)?.status));
       },
     });
   }
@@ -437,9 +451,32 @@ export abstract class BaseAuthService extends BaseRestService {
     return this.http.post<{ message: string }>(this.profilePhoneConfirmUrl, { value, code });
   }
 
-  confirmRegister(email: string, code: string) {
+  /** Confirm a registration; success completes the login from the tokens keel
+   *  answers. A registration without partner fields leaves `partnerId` 0. */
+  confirmRegister(email: string, code: string): Observable<ConfirmRegisterResponse> {
     const params = new HttpParams().set('email', email).set('code', code);
-    return this.http.post<ConfirmRegisterResponse>(this.confirmRegisterUrl, null, { params });
+    return this.http.post<ConfirmRegisterResponse>(this.confirmRegisterUrl, null, { params }).pipe(
+        tap((res) => this.completeLogin(res.token, res.refreshToken)),
+    );
+  }
+
+  /** Create the partner of a signed-in user who has none, then rotate the
+   *  refresh token so the session carries the partner. An error after keel
+   *  created the partner means only the rotation failed; do not post again. */
+  createPartner(setup: PartnerSetup): Observable<PartnerCreated> {
+    return this.http.post<PartnerCreated>(this.registerPartnerUrl, setup).pipe(
+        mergeMap((created) => this.refreshSession().pipe(
+            tap((token) => this.completeLogin(token, localStorage.getItem('refreshToken') ?? undefined)),
+            map(() => created),
+        )),
+    );
+  }
+
+  /** Trade keel's single-use hand-off code for a session; same contract as login(). */
+  exchangeHandoff(code: string): Observable<LoginResponse2FA> {
+    return this.http.post<LoginResponse2FA>(this.registerExchangeUrl, { code }, { withCredentials: true }).pipe(
+        tap((res) => this.handleLoginResponse(res)),
+    );
   }
 
   confirmChpass(username: string, code: string, new_password: string) {
@@ -448,11 +485,12 @@ export abstract class BaseAuthService extends BaseRestService {
 
   loadStoredSession() {
     this.token = localStorage.getItem('jwt');
-    if (this.token) {
-      this.isLoggedIn.set(true);
-      this.loadAppData();
-      this.initRoutes();
-    }
+    if (!this.token) return;
+    this.isLoggedIn.set(true);
+    // A signed-in user sent to the login page by the authorization server is handed off without signing in again.
+    if (window.location.pathname.startsWith('/login') && this.startHandoff()) return;
+    this.loadAppData();
+    this.initRoutes();
   }
 
   /** Revoke the refresh token server-side (best effort: the local session is
@@ -472,7 +510,7 @@ export abstract class BaseAuthService extends BaseRestService {
   }
 
   register(reg: PartnerRegistration) {
-    return this.http.post<PartnerRegistration>(this.registerUrl, reg);
+    return this.http.post<{ status: string }>(this.registerUrl, reg);
   }
 
   // ── Phone / email OTP ──

package/src/service/rest_url.ts

@@ -9,7 +9,9 @@ export const RestURL = {
   loginGoogleURL: '/public/login/google',
   registerURL: '/public/register',
   chpassURL: '/public/login/chpass',
-  confirmRegisterURL: '/public/confirm/register',
+  confirmRegisterURL: '/public/register/confirm',
+  registerExchangeURL: '/public/register/exchange',
+  registerPartnerURL: '/api/register/partner',
   plansURL: '/public/plans',
   confirmChpassURL: '/public/confirm/password',
   twoFactorSetupURL: '/api/user/2fa/setup',