@nauticana/sail 0.5.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@nauticana/sail",
+  "version": "0.5.0",
+  "description": "Metadata-driven Angular component library for CRUD admin frontends backed by the keel Go backend. Tables, forms, navigation, OTP/2FA/social auth, billing.",
+  "main": "src/index.ts",
+  "files": [
+    "src/",
+    "tsconfig.json"
+  ],
+  "keywords": [
+    "angular",
+    "angular-library",
+    "crud",
+    "admin",
+    "keel",
+    "nauticana",
+    "metadata-driven",
+    "material",
+    "auth",
+    "2fa",
+    "otp"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nauticana",
+  "homepage": "https://github.com/nauticana/sail#readme",
+  "bugs": {
+    "url": "https://github.com/nauticana/sail/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nauticana/sail.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@angular/cdk": "^21.0.0",
+    "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "@angular/forms": "^21.0.0",
+    "@angular/material": "^21.0.0",
+    "@angular/router": "^21.0.0",
+    "class-validator": "^0.15.1",
+    "rxjs": "~7.8.0"
+  },
+  "devDependencies": {
+    "@angular/cdk": "^21.2.6",
+    "@angular/common": "^21.2.8",
+    "@angular/compiler": "^21.2.8",
+    "@angular/core": "^21.2.8",
+    "@angular/forms": "^21.2.8",
+    "@angular/material": "^21.2.6",
+    "@angular/router": "^21.2.8",
+    "class-validator": "^0.15.1",
+    "rxjs": "~7.8.0",
+    "typescript": "~5.9.2"
+  }
+}

package/src/component/abstract/base_async.ts

@@ -0,0 +1,49 @@
+import { signal } from '@angular/core';
+import { Observable } from 'rxjs';
+
+/**
+ * Base class for components that perform async operations and need to show
+ * loading / error / success state. Reduces the same signal boilerplate
+ * across billing, security, and registration components.
+ *
+ * Subclasses use `run(obs, onSuccess, fallbackError)` to wire an Observable
+ * into the shared state automatically.
+ */
+export abstract class BaseAsync {
+  readonly loading = signal(false);
+  readonly errorMessage = signal('');
+  readonly successMessage = signal('');
+
+  /** Clear any prior messages. */
+  protected clearMessages(): void {
+    this.errorMessage.set('');
+    this.successMessage.set('');
+  }
+
+  /** Set errorMessage from an HTTP error object; falls back to `fallback`. */
+  protected setError(err: any, fallback: string): void {
+    this.errorMessage.set(err?.error?.message ?? fallback);
+    this.loading.set(false);
+  }
+
+  /**
+   * Subscribe to an Observable with shared loading/error semantics.
+   * Clears messages, sets loading, invokes onSuccess on next, and routes
+   * errors through setError with the given fallback message.
+   */
+  protected run<T>(
+    obs: Observable<T>,
+    onSuccess: (value: T) => void,
+    fallbackError = 'Operation failed. Please try again.',
+  ): void {
+    this.clearMessages();
+    this.loading.set(true);
+    obs.subscribe({
+      next: (value) => {
+        this.loading.set(false);
+        onSuccess(value);
+      },
+      error: (err) => this.setError(err, fallbackError),
+    });
+  }
+}

package/src/component/abstract/base_form.ts

@@ -0,0 +1,11 @@
+import { BaseTable } from "./base_table";
+
+export abstract class BaseForm extends BaseTable {
+    editableRecord: {[key: string]: any} = {};
+    isNew = false;
+    title = '';
+
+    override isReadOnly(fieldName: string): boolean {
+        return !this.isNew && this.isKey(fieldName);
+    }
+}

package/src/component/abstract/base_table.ts

@@ -0,0 +1,320 @@
+import { inject } from "@angular/core";
+import { ForeignKey, TableColumn, TableDefinition } from "../../model/appdata";
+import { ConstantValue } from "../../model/common";
+import { BaseAuthService } from "../../service/auth.service";
+import { SAIL_GUI_CONFIG, SailGuiConfig, DEFAULT_CONFIG } from "../../config";
+
+
+export abstract class BaseTable {
+    protected readonly cacheService = inject(BaseAuthService);
+    protected readonly config: SailGuiConfig = inject(SAIL_GUI_CONFIG, {optional: true}) ?? DEFAULT_CONFIG;
+    protected readonly dialogWidth: string = '400px';
+    tableName = '';
+    caption = '';
+    fieldOptions: {[key: string]: ConstantValue[]} = {};
+    fieldLabels: {[key: string]: string} = {};
+    isReadOnlyBound = this.isReadOnly.bind(this);
+
+    isReadOnly(_fieldName: string): boolean {
+        return false;
+    }
+
+    titleCase(str: string): string {
+        return str.replaceAll('_', ' ').toLowerCase().split(' ').map((word: string) => {
+                return word.charAt(0).toUpperCase() + word.slice(1);
+        }).join(' ');
+    }
+
+    getCaption() {
+        if (!this.caption) {
+            this.caption = this.titleCase(this.tableName);
+        }
+        return this.caption;
+    }
+
+    colCaption(fieldName: string): string {
+        if (!this.fieldLabels[fieldName]) {
+            const col = this.getColumn(fieldName);
+            this.fieldLabels[fieldName] = col?.Caption || this.titleCase(fieldName);
+        }
+        return this.fieldLabels[fieldName];
+    }
+
+    canRead() {
+        return this.cacheService.canRead(this.tableName);
+    }
+
+    canCreate() {
+        return this.cacheService.canCreate(this.tableName);
+    }
+
+    canUpdate() {
+        return this.cacheService.canUpdate(this.tableName);
+    }
+
+    canDelete() {
+        return this.cacheService.canDelete(this.tableName);
+    }
+
+    emptyRecord(): any {
+        const record : any = {[this.config.opField]: 'I'}
+        const tableDef = this.cacheService.getTableDefinition(this.tableName);
+        const tableOverride = this.config.tableOverrides?.[this.tableName];
+        const editableTimestamps = new Set(tableOverride?.editableTimestamps ?? []);
+
+        if (tableDef) {
+            if (tableDef.Columns) {
+                tableDef.Columns.forEach((field) => {
+                    if (field.SequenceName) {
+                        return; // auto-generated by database sequence
+                    }
+                    if (field.HasDefault && field.DataType === 'timestamp'
+                        && !editableTimestamps.has(field.PascalName)) {
+                        return; // audit column — server-managed, don't include
+                    }
+                    if (field.HasDefault && field.DataType !== 'timestamp') {
+                        record[field.PascalName] = field.DataType === 'boolean'
+                            ? field.DefaultValue === 'true'
+                            : field.DefaultValue;
+                    } else {
+                        record[field.PascalName] = field.DataType === 'boolean' ? false : '';
+                    }
+                });
+            }
+            if (tableDef.Children) {
+                tableDef.Children.forEach((child) => {
+                    record[child.PascalName] = [];
+                });
+            }
+            // Apply per-table default values from SailGuiConfig.tableOverrides (overrides DB defaults).
+            // Values may be literals or zero-arg functions (evaluated now).
+            const overrideDefaults = tableOverride?.defaultValues;
+            if (overrideDefaults) {
+                for (const [key, value] of Object.entries(overrideDefaults)) {
+                    record[key] = typeof value === 'function' ? (value as () => unknown)() : value;
+                }
+            }
+        }
+        return record;
+    }
+
+    getDisplayedColumns(records: any[] = []): string[] {
+        const tableDef = this.cacheService.getTableDefinition(this.tableName);
+        const tableOverride = this.config.tableOverrides?.[this.tableName];
+        const hidden = new Set([
+            ...this.config.hiddenFields,
+            ...(tableOverride?.hiddenFields ?? []),
+        ]);
+        const editableTimestamps = new Set(tableOverride?.editableTimestamps ?? []);
+        if (tableDef && tableDef.Columns && tableDef.Columns.length > 0) {
+            return tableDef.Columns
+                .filter(col => !(col.HasDefault && col.DataType === 'timestamp'
+                                 && !editableTimestamps.has(col.PascalName)))
+                .sort((a, b) => a.Order - b.Order)
+                .map((field) => field.PascalName)
+                .filter(name => !hidden.has(name));
+        } else if (records.length > 0) {
+            return Object.keys(records[0]).filter(name => !hidden.has(name));
+        }
+        return [];
+    }
+
+    getColumn(fieldName: string): TableColumn | undefined {
+        const tableDef = this.cacheService.getTableDefinition(this.tableName);
+        if (tableDef && tableDef.Columns) {
+            return tableDef.Columns.find((field) => field.PascalName === fieldName);
+        }
+        return undefined;
+    }
+
+    displayValue(fieldName: string, rawValue: any): string {
+        if (rawValue === null || rawValue === undefined || rawValue === '') return '';
+        const col = this.getColumn(fieldName);
+        if (!col) return String(rawValue);
+        if (col.LookupDomain) {
+            const options = this.cacheService.getDomainValues(col.LookupDomain);
+            const match = options?.find(o => o.Value === String(rawValue));
+            if (match) return match.Caption ?? String(rawValue);
+        }
+        if (col.LookupTable && col.LookupStyle === 'D') {
+            const options = this.cacheService.getTableValues(col.LookupTable);
+            const match = options?.find(o => o.Value === String(rawValue));
+            if (match) return match.Caption ?? String(rawValue);
+        }
+        return String(rawValue);
+    }
+
+    isTimeStamp(fieldName: string): boolean {
+        const col = this.getColumn(fieldName)
+        if (col) {
+            return col.DataType === 'timestamp';
+        }
+        return fieldName.endsWith('Time') || fieldName.endsWith('time');
+    }
+
+    isNumber(fieldName: string): boolean {
+        const col = this.getColumn(fieldName)
+        if (col) {
+            return col.DataType === 'integer' || col.DataType === 'float';
+        }
+        return false;
+    }
+
+    isBoolean(fieldName: string): boolean {
+        const col = this.getColumn(fieldName)
+        if (col) {
+            return col.DataType === 'boolean' || col.LookupDomain === 'BOOLEAN';
+        }
+        return false;
+    }
+
+    isKey(fieldName: string): boolean {
+        const col = this.getColumn(fieldName)
+        if (col) {
+            return (col.IsKey);
+        }
+        return false;
+    }
+
+    isArray(value: any): boolean {
+        return Array.isArray(value);
+    }
+
+    formatTimeStamp(val: string): string {
+        if (val && typeof val === 'string') {
+            return val.slice(0, 16);
+        }
+        return val;
+    }
+
+    formatRecordTimeStamp(record: any) {
+        if (record) {
+            for (const key of Object.keys(record)) {
+                if (this.isTimeStamp(key)) {
+                    record[key] = this.formatTimeStamp(record[key]);
+                }
+            }
+        }
+    }
+
+    restoreTimeStamp(val: any): any {
+        // PostgreSQL can't cast '' to TIMESTAMP — normalize empty to null.
+        if (val === '' || val === undefined || val === null) return null;
+        if (typeof val === 'string' && !val.endsWith('Z')) {
+            return val + ':00Z';
+        }
+        return val;
+    }
+
+    restoreRecordTimeStamp(record: any) {
+        if (record) {
+            for (const key of Object.keys(record)) {
+                if (this.isTimeStamp(key)) {
+                    record[key] = this.restoreTimeStamp(record[key]);
+                }
+            }
+        }
+    }
+
+    readyToSave(record: any, original?: any) {
+        this.restoreRecordTimeStamp(record);
+        const op = record[this.config.opField];
+        if (op === 'I' || op === 'D') return; // already marked
+        // Original snapshot may carry display-formatted timestamps; restore both
+        // sides to the same wire format before comparing, otherwise scalar
+        // fields like Passdate look "modified" purely due to formatting.
+        if (original) {
+            const normalized = { ...original };
+            this.restoreRecordTimeStamp(normalized);
+            if (!this.isRecordDirty(record, normalized)) {
+                record[this.config.opField] = 'R';
+                return;
+            }
+        }
+        record[this.config.opField] = 'U';
+    }
+
+    /** Shallow compare of own scalar fields, ignoring child arrays and op_code. */
+    isRecordDirty(current: any, original: any): boolean {
+        const opField = this.config.opField;
+        for (const key of Object.keys(current)) {
+            if (key === opField) continue;
+            const curVal = current[key];
+            // Ignore child-relation arrays; those have their own op_code per row.
+            if (Array.isArray(curVal)) continue;
+            if (curVal !== original[key]) return true;
+        }
+        return false;
+    }
+
+    getDialogData(record: any, isNew: boolean, readOnlyColumns: string[] = []): any {
+        return {record, tableName: this.tableName, isNew, readOnlyColumns};
+    }
+
+    getTableName(fieldName: string): string {
+        const tableDef = this.cacheService.getTableDefinition(this.tableName);
+        if (!tableDef) return '';
+        const fk = tableDef.Children?.find((c) => c.PascalName === fieldName);
+        return fk ? fk.ChildTable : '';
+    }
+
+    getOptions(fieldName: string): ConstantValue[] | undefined {
+        if (this.fieldOptions[fieldName]) {
+            return this.fieldOptions[fieldName];
+        }
+        const col = this.getColumn(fieldName)
+        if (col && col.LookupDomain) {
+            return this.cacheService.getDomainValues(col.LookupDomain);
+        }
+        if (col && col.LookupTable && col.LookupStyle === 'D') {
+            return this.cacheService.getTableValues(col.LookupTable);
+        }
+        return undefined;
+    }
+
+    getKeyFilters(record: any): {[key: string]: string} | undefined {
+        const tableDef = this.cacheService.getTableDefinition(this.tableName);
+        if (!tableDef || !tableDef.Keys || tableDef.Keys.length === 0) {
+            return undefined;
+        }
+        const filters: {[key: string]: string} = {};
+        for (const key of tableDef.Keys) {
+            filters[key.PascalName] = record[key.PascalName];
+        }
+        return filters;
+    }
+
+    getForeignKeyConfig(parentTable: string): {fk: ForeignKey, parent: TableDefinition} | null{
+        if (!parentTable) return null;
+        const tableDef = this.cacheService.getTableDefinition(this.tableName);
+        const parent = this.cacheService.getTableDefinition(parentTable);
+        if (!tableDef || !tableDef.Keys || !tableDef.Parents || !parent) return null;
+        const fk = tableDef.Parents.find((parent) => parent.ParentTable === parentTable);
+        if (!fk) return null;
+        return {'fk': fk, 'parent': parent};
+    }
+
+    initializeForeignKeys(record: any, parentTable: string, parentRecord: any) {
+        const readOnlyColumns: string[] = [];
+        const fkData = this.getForeignKeyConfig(parentTable);
+        if (fkData && fkData.fk && fkData.parent) {
+            fkData.fk.Columns.forEach((column, index) => {
+                record[column.PascalName] = parentRecord[fkData.parent.Keys[index].PascalName];
+                readOnlyColumns.push(column.PascalName);
+            });
+        }
+    }
+
+    buildSearchTerms(record: {[key: string]: any}): {[key: string]: string} {
+        const hiddenSet = new Set(this.config.hiddenFields);
+        const searchTerms: {[key: string]: string} = {};
+        for (const key of Object.keys(record)) {
+            if (hiddenSet.has(key)) continue;
+            const val = record[key];
+            if (val !== '' && val !== null && val !== undefined && !Array.isArray(val)) {
+                searchTerms[key] = val;
+            }
+        }
+        return searchTerms;
+    }
+}

package/src/component/abstract/base_view.ts

@@ -0,0 +1,93 @@
+import { Directive, inject, Input } from "@angular/core";
+import { BaseTable } from "./base_table";
+import { MatDialog } from "@angular/material/dialog";
+
+@Directive()
+export abstract class BaseView extends BaseTable {
+    protected readonly dialog = inject(MatDialog);
+    @Input() override tableName = '';
+    @Input() apiName = '';
+    @Input() dialogComponent: any;
+    records: Array<{[key: string]: any}> = [];
+    displayedColumns: string[] = [];
+    searchTerms: {[key: string]: string} = {};
+    protected hasLinkPermission = false;
+
+    protected abstract handleDelete(record: {[key: string]: any}): void;
+
+    protected abstract handleUpdate(result: {[key: string]: any}, isNew: boolean, original: {[key: string]: any}): void;
+
+    updateDisplayedColumns(record: Array<{[key: string]: any}>) {
+        this.displayedColumns = this.getDisplayedColumns(record);
+        if (this.displayedColumns.length > 0 &&
+            !this.displayedColumns.includes('actions') &&
+            (this.canUpdate() || this.canDelete())
+        ) this.displayedColumns.push('actions');
+        this.hasLinkPermission = this.canUpdate() || this.canRead();
+    }
+
+    isLinkColumn(column: string): boolean {
+        return (this.displayedColumns.length > 0 && this.displayedColumns[0] === column && this.hasLinkPermission);
+    }
+
+    trackByRecord(index: number, record: {[key: string]: any}): any {
+        const tableDef = this.cacheService.getTableDefinition(this.tableName);
+        if (!tableDef || !tableDef.Keys || tableDef.Keys.length === 0) return index;
+        return tableDef.Keys.map((key) => record[key.PascalName]).join('_');
+    }
+
+    addRecord() {
+        if (!this.canCreate()) {
+            alert('Missing authorization to create records');
+            return;
+        }
+        const record = this.emptyRecord();
+
+        if (Object.keys(record).length === 1 && this.records.length > 0) {
+            Object.keys(this.records[0]).forEach((key) => {
+                record[key] = '';
+            });
+        }
+
+        const dialogRef = this.dialog.open(this.dialogComponent, {
+            width: '90vw',
+            maxWidth: '1200px',
+            maxHeight: '90vh',
+            disableClose: true,
+            data: this.getDialogData(record, true),
+        });
+
+        dialogRef.afterClosed().subscribe((result) => {
+            if (result) this.handleUpdate(result, true, {});
+        });
+    }
+
+    editRecord(record: {[key: string]: any}) {
+        if (!this.canUpdate()) {
+            alert('Missing authorization to update records');
+            return;
+        }
+        const dialogData = this.getDialogData(record, false);
+        if (this.apiName) {
+            dialogData['apiName'] = this.apiName;
+        }
+        const dialogRef = this.dialog.open(this.dialogComponent, {
+            width: '90vw',
+            maxWidth: '1200px',
+            maxHeight: '90vh',
+            disableClose: true,
+            data: dialogData,
+        });
+        dialogRef.afterClosed().subscribe((result) => {
+            if (result) this.handleUpdate(result, false, record);
+        });
+    }
+
+    deleteRecord(record: {[key: string]: any}) {
+        if (!this.canDelete()) {
+            alert('Missing authorization to delete records');
+            return;
+        }
+        this.handleDelete(record);
+    }
+}

package/src/component/billing/checkout_button.html

@@ -0,0 +1,10 @@
+<div class="checkout-button">
+  <button mat-raised-button class="primary" type="button"
+          [disabled]="loading()"
+          (click)="startCheckout()">
+    @if (loading()) { Starting checkout… } @else { {{ label() }} }
+  </button>
+  @if (errorMessage()) {
+    <div class="auth-error" role="alert">{{ errorMessage() }}</div>
+  }
+</div>

package/src/component/billing/checkout_button.ts

@@ -0,0 +1,57 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation, inject, input } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { BaseAsync } from '../abstract/base_async';
+import { BillingService } from '../../service/billing.service';
+import { CheckoutMode } from '../../model/appdata';
+
+/**
+ * Button that opens a provider-hosted checkout session and redirects the
+ * browser to the returned URL. Uses BaseAsync for loading/error state.
+ *
+ * The keel backend validates `priceId`, `successUrl`, and `cancelUrl`
+ * against server-side allowlists. Any value outside the allowlist is
+ * rejected with 400.
+ */
+@Component({
+  selector: 'app-checkout-button',
+  templateUrl: './checkout_button.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule],
+})
+export class CheckoutButtonComponent extends BaseAsync {
+  private readonly billing = inject(BillingService);
+
+  /** Stripe price ID (or keel-internal plan id resolved server-side). */
+  readonly priceId = input.required<string>();
+  /** Checkout mode — 'subscription' (default), 'payment' (one-off), or 'setup' (capture method). */
+  readonly mode = input<CheckoutMode>('subscription');
+  /** Quantity for the priced item. */
+  readonly quantity = input<number | undefined>(undefined);
+  /** Pre-filled email passed to the provider. */
+  readonly email = input<string | undefined>(undefined);
+  /** Redirect URL after success — must match keel AllowedRedirectHosts. */
+  readonly successUrl = input.required<string>();
+  /** Redirect URL after cancel — must match keel AllowedRedirectHosts. */
+  readonly cancelUrl = input.required<string>();
+  /** Optional metadata bag forwarded to the provider session. */
+  readonly metadata = input<{ [key: string]: string } | undefined>(undefined);
+  /** Button label. */
+  readonly label = input('Continue to payment');
+
+  startCheckout(): void {
+    this.run(
+      this.billing.createCheckout({
+        mode:       this.mode(),
+        priceId:    this.priceId(),
+        quantity:   this.quantity(),
+        email:      this.email(),
+        successUrl: this.successUrl(),
+        cancelUrl:  this.cancelUrl(),
+        metadata:   this.metadata(),
+      }),
+      (resp) => { window.location.href = resp.checkoutUrl; },
+      'Could not start checkout. Please try again.',
+    );
+  }
+}

package/src/component/billing/payment_methods.html

@@ -0,0 +1,27 @@
+<div class="payment-methods">
+  <h3 class="payment-methods-title">Payment methods</h3>
+
+  @if (loading()) {
+    <p class="empty-state">Loading…</p>
+  } @else if (methods().length > 0) {
+    <ul class="payment-methods-list">
+      @for (method of methods(); track method.id) {
+        <li class="payment-method">
+          <span class="payment-method-label">
+            {{ method.provider }} · {{ method.methodType }}
+            @if (method.last4) { · •••• {{ method.last4 }} }
+          </span>
+          @if (method.isDefault) {
+            <span class="payment-default-badge">Default</span>
+          }
+        </li>
+      }
+    </ul>
+  } @else {
+    <p class="empty-state">No payment methods on file.</p>
+  }
+
+  @if (errorMessage()) {
+    <div class="auth-error" role="alert">{{ errorMessage() }}</div>
+  }
+</div>

package/src/component/billing/payment_methods.ts

@@ -0,0 +1,36 @@
+import { ChangeDetectionStrategy, Component, OnInit, ViewEncapsulation, inject, signal } from '@angular/core';
+import { MatButtonModule } from '@angular/material/button';
+import { MatIconModule } from '@angular/material/icon';
+import { BaseAsync } from '../abstract/base_async';
+import { BillingService } from '../../service/billing.service';
+import { PaymentMethod } from '../../model/appdata';
+
+/**
+ * Lists the partner's saved payment methods. Inherits loading/error state
+ * from BaseAsyncView. The "Manage in Stripe" button is a placeholder — pass
+ * `[portalUrl]` to show it; otherwise the button is hidden.
+ */
+@Component({
+  selector: 'app-payment-methods',
+  templateUrl: './payment_methods.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  imports: [MatButtonModule, MatIconModule],
+})
+export class PaymentMethodsComponent extends BaseAsync implements OnInit {
+  private readonly billing = inject(BillingService);
+
+  readonly methods = signal<PaymentMethod[]>([]);
+
+  ngOnInit(): void {
+    this.load();
+  }
+
+  load(): void {
+    this.run(
+      this.billing.listPaymentMethods(),
+      (list) => this.methods.set(list ?? []),
+      'Failed to load payment methods.',
+    );
+  }
+}