@maravilla-labs/platform 0.1.36 → 0.1.38

package/dist/config.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.
+ *
+ * Declares your project's auth settings (resources, groups, relations,
+ * registration fields, OAuth providers, security policy, branding) alongside
+ * your code. The Maravilla adapter reads this at build time and reconciles
+ * the settings into delivery on deploy.
+ *
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [
+ *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],
+ *         policy: 'auth.user_id == node.owner' },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * Omitted sections leave the DB alone — partial adoption is explicitly
+ * supported. List-based sections (`resources`, `groups`, `relations`,
+ * `oauth`) are upserted and never auto-delete DB-only entries. Singleton
+ * sections (`registration`, `security`, `branding`) are replaced wholesale
+ * when declared.
+ */
+/**
+ * String value that may either be a literal secret or a reference to an
+ * environment variable on the **tenant** (resolved server-side at
+ * reconcile time, never shipped plaintext in the manifest).
+ *
+ * Accepted forms:
+ *   - `"literal-value"` — inline (not recommended for real secrets)
+ *   - `"${env.VAR_NAME}"` — string-template form
+ *   - `{ env: "VAR_NAME" }` — object form
+ */
+type SecretRef = string | {
+    env: string;
+};
+interface ResourceDefinition {
+    /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */
+    name: string;
+    /** Human-readable title for the admin UI. */
+    title: string;
+    /** Optional longer description. */
+    description?: string;
+    /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */
+    actions: string[];
+    /**
+     * Optional raisin-rel policy expression. Evaluated on every KV/DB/
+     * realtime/media op that targets this resource. Leave empty to skip
+     * Layer 2 for this resource — tenant + owner isolation still applies.
+     */
+    policy?: string;
+}
+interface GroupPermissionDefinition {
+    /** Must match a `ResourceDefinition.name`. */
+    resource_name: string;
+    /** Actions this group is granted on the resource. */
+    actions: string[];
+}
+interface GroupDefinition {
+    /** Unique group name per tenant. */
+    name: string;
+    /** Optional description for the admin UI. */
+    description?: string;
+    /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */
+    permissions?: GroupPermissionDefinition[];
+}
+interface RelationTypeDefinition {
+    /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */
+    relation_name: string;
+    /** Human-readable title. */
+    title: string;
+    description?: string;
+    /** Grouping for the admin UI (e.g. `"family"`, `"work"`). */
+    category?: string;
+    icon?: string;
+    color?: string;
+    /** Name of the inverse relation type, if one exists. */
+    inverse_relation_name?: string;
+    /** When true, membership in this relation implies stewardship rights. */
+    implies_stewardship?: boolean;
+    /** When true, the relation can only target users flagged as minors. */
+    requires_minor?: boolean;
+    /** When true, the relation is symmetric (A→B implies B→A). */
+    bidirectional?: boolean;
+}
+interface RegistrationFieldDefinition {
+    /** Field key used as the form field name + in profile data. */
+    key: string;
+    /** Display label. */
+    label: string;
+    /** One of: text, email, phone, date, number, select, boolean, url, textarea. */
+    field_type: string;
+    required: boolean;
+    show_on_register: boolean;
+    /** Optional validation metadata — passed through to the UI. */
+    validation?: Record<string, unknown>;
+}
+interface RegistrationConfig {
+    /** Ordered list of custom registration fields. Declaring this replaces the full list. */
+    fields: RegistrationFieldDefinition[];
+}
+interface OAuthProviderDefinition {
+    enabled: boolean;
+    client_id: string;
+    /** Prefer `{ env: "VAR_NAME" }` or `"${env.VAR_NAME}"`. */
+    client_secret: SecretRef;
+    scopes: string[];
+    /** Only for `custom_oidc`. */
+    discovery_url?: string;
+}
+interface OAuthProvidersConfig {
+    google?: OAuthProviderDefinition;
+    github?: OAuthProviderDefinition;
+    okta?: OAuthProviderDefinition;
+    custom_oidc?: OAuthProviderDefinition;
+}
+interface PasswordPolicyDefinition {
+    min_length: number;
+    require_uppercase: boolean;
+    require_number: boolean;
+    require_special: boolean;
+}
+interface SessionConfigDefinition {
+    access_token_ttl_secs: number;
+    refresh_token_ttl_secs: number;
+    max_sessions_per_user: number;
+    require_email_verification: boolean;
+}
+interface SecurityConfig {
+    password_policy?: PasswordPolicyDefinition;
+    session?: SessionConfigDefinition;
+}
+interface BrandingConfig {
+    app_name?: string;
+    logo_url?: string;
+    primary_color?: string;
+    secondary_color?: string;
+    welcome_message?: string;
+    welcome_subtitle?: string;
+    /** `"centered"`, `"split-left"`, `"split-right"`, or `"fullscreen"`. */
+    layout?: string;
+    background_image_url?: string;
+    /** 0–100 percentage. */
+    background_focal_point?: {
+        x: number;
+        y: number;
+    };
+    background_gradient?: string;
+    /** `"light"`, `"dark"`, or `"auto"`. */
+    color_mode?: string;
+    font_family?: string;
+    terms_url?: string;
+    privacy_url?: string;
+    /** Raw CSS merged into the hosted auth pages. */
+    custom_css?: string;
+}
+interface AuthConfigBlock {
+    resources?: ResourceDefinition[];
+    groups?: GroupDefinition[];
+    relations?: RelationTypeDefinition[];
+    registration?: RegistrationConfig;
+    oauth?: OAuthProvidersConfig;
+    security?: SecurityConfig;
+    branding?: BrandingConfig;
+}
+interface MaravillaConfig {
+    /** All project-level auth settings. Every field is optional — partial adoption is supported. */
+    auth?: AuthConfigBlock;
+}
+/**
+ * Identity function that returns the config unchanged — exists purely so the
+ * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense
+ * on every field.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],
+ *   },
+ * });
+ * ```
+ */
+declare function defineConfig(config: MaravillaConfig): MaravillaConfig;
+
+export { type AuthConfigBlock, type BrandingConfig, type GroupDefinition, type GroupPermissionDefinition, type MaravillaConfig, type OAuthProviderDefinition, type OAuthProvidersConfig, type PasswordPolicyDefinition, type RegistrationConfig, type RegistrationFieldDefinition, type RelationTypeDefinition, type ResourceDefinition, type SecretRef, type SecurityConfig, type SessionConfigDefinition, defineConfig };

package/dist/config.js

@@ -0,0 +1,8 @@
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["/**\n * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.\n *\n * Declares your project's auth settings (resources, groups, relations,\n * registration fields, OAuth providers, security policy, branding) alongside\n * your code. The Maravilla adapter reads this at build time and reconciles\n * the settings into delivery on deploy.\n *\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [\n *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],\n *         policy: 'auth.user_id == node.owner' },\n *     ],\n *   },\n * });\n * ```\n *\n * Omitted sections leave the DB alone — partial adoption is explicitly\n * supported. List-based sections (`resources`, `groups`, `relations`,\n * `oauth`) are upserted and never auto-delete DB-only entries. Singleton\n * sections (`registration`, `security`, `branding`) are replaced wholesale\n * when declared.\n */\n\n/**\n * String value that may either be a literal secret or a reference to an\n * environment variable on the **tenant** (resolved server-side at\n * reconcile time, never shipped plaintext in the manifest).\n *\n * Accepted forms:\n *   - `\"literal-value\"` — inline (not recommended for real secrets)\n *   - `\"${env.VAR_NAME}\"` — string-template form\n *   - `{ env: \"VAR_NAME\" }` — object form\n */\nexport type SecretRef = string | { env: string };\n\n// ── Resources + policies ──\n\nexport interface ResourceDefinition {\n  /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */\n  name: string;\n  /** Human-readable title for the admin UI. */\n  title: string;\n  /** Optional longer description. */\n  description?: string;\n  /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */\n  actions: string[];\n  /**\n   * Optional raisin-rel policy expression. Evaluated on every KV/DB/\n   * realtime/media op that targets this resource. Leave empty to skip\n   * Layer 2 for this resource — tenant + owner isolation still applies.\n   */\n  policy?: string;\n}\n\n// ── Groups ──\n\nexport interface GroupPermissionDefinition {\n  /** Must match a `ResourceDefinition.name`. */\n  resource_name: string;\n  /** Actions this group is granted on the resource. */\n  actions: string[];\n}\n\nexport interface GroupDefinition {\n  /** Unique group name per tenant. */\n  name: string;\n  /** Optional description for the admin UI. */\n  description?: string;\n  /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */\n  permissions?: GroupPermissionDefinition[];\n}\n\n// ── Relations ──\n\nexport interface RelationTypeDefinition {\n  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */\n  relation_name: string;\n  /** Human-readable title. */\n  title: string;\n  description?: string;\n  /** Grouping for the admin UI (e.g. `\"family\"`, `\"work\"`). */\n  category?: string;\n  icon?: string;\n  color?: string;\n  /** Name of the inverse relation type, if one exists. */\n  inverse_relation_name?: string;\n  /** When true, membership in this relation implies stewardship rights. */\n  implies_stewardship?: boolean;\n  /** When true, the relation can only target users flagged as minors. */\n  requires_minor?: boolean;\n  /** When true, the relation is symmetric (A→B implies B→A). */\n  bidirectional?: boolean;\n}\n\n// ── Registration fields ──\n\nexport interface RegistrationFieldDefinition {\n  /** Field key used as the form field name + in profile data. */\n  key: string;\n  /** Display label. */\n  label: string;\n  /** One of: text, email, phone, date, number, select, boolean, url, textarea. */\n  field_type: string;\n  required: boolean;\n  show_on_register: boolean;\n  /** Optional validation metadata — passed through to the UI. */\n  validation?: Record<string, unknown>;\n}\n\nexport interface RegistrationConfig {\n  /** Ordered list of custom registration fields. Declaring this replaces the full list. */\n  fields: RegistrationFieldDefinition[];\n}\n\n// ── OAuth providers ──\n\nexport interface OAuthProviderDefinition {\n  enabled: boolean;\n  client_id: string;\n  /** Prefer `{ env: \"VAR_NAME\" }` or `\"${env.VAR_NAME}\"`. */\n  client_secret: SecretRef;\n  scopes: string[];\n  /** Only for `custom_oidc`. */\n  discovery_url?: string;\n}\n\nexport interface OAuthProvidersConfig {\n  google?: OAuthProviderDefinition;\n  github?: OAuthProviderDefinition;\n  okta?: OAuthProviderDefinition;\n  custom_oidc?: OAuthProviderDefinition;\n}\n\n// ── Security ──\n\nexport interface PasswordPolicyDefinition {\n  min_length: number;\n  require_uppercase: boolean;\n  require_number: boolean;\n  require_special: boolean;\n}\n\nexport interface SessionConfigDefinition {\n  access_token_ttl_secs: number;\n  refresh_token_ttl_secs: number;\n  max_sessions_per_user: number;\n  require_email_verification: boolean;\n}\n\nexport interface SecurityConfig {\n  password_policy?: PasswordPolicyDefinition;\n  session?: SessionConfigDefinition;\n}\n\n// ── Branding ──\n\nexport interface BrandingConfig {\n  app_name?: string;\n  logo_url?: string;\n  primary_color?: string;\n  secondary_color?: string;\n  welcome_message?: string;\n  welcome_subtitle?: string;\n  /** `\"centered\"`, `\"split-left\"`, `\"split-right\"`, or `\"fullscreen\"`. */\n  layout?: string;\n  background_image_url?: string;\n  /** 0–100 percentage. */\n  background_focal_point?: { x: number; y: number };\n  background_gradient?: string;\n  /** `\"light\"`, `\"dark\"`, or `\"auto\"`. */\n  color_mode?: string;\n  font_family?: string;\n  terms_url?: string;\n  privacy_url?: string;\n  /** Raw CSS merged into the hosted auth pages. */\n  custom_css?: string;\n}\n\n// ── Top-level shape ──\n\nexport interface AuthConfigBlock {\n  resources?: ResourceDefinition[];\n  groups?: GroupDefinition[];\n  relations?: RelationTypeDefinition[];\n  registration?: RegistrationConfig;\n  oauth?: OAuthProvidersConfig;\n  security?: SecurityConfig;\n  branding?: BrandingConfig;\n}\n\nexport interface MaravillaConfig {\n  /** All project-level auth settings. Every field is optional — partial adoption is supported. */\n  auth?: AuthConfigBlock;\n}\n\n/**\n * Identity function that returns the config unchanged — exists purely so the\n * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense\n * on every field.\n *\n * @example\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],\n *   },\n * });\n * ```\n */\nexport function defineConfig(config: MaravillaConfig): MaravillaConfig {\n  return config;\n}\n"],"mappings":";AAwNO,SAAS,aAAa,QAA0C;AACrE,SAAO;AACT;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js"
     }
   },
   "scripts": {

package/src/config.ts

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.
+ *
+ * Declares your project's auth settings (resources, groups, relations,
+ * registration fields, OAuth providers, security policy, branding) alongside
+ * your code. The Maravilla adapter reads this at build time and reconciles
+ * the settings into delivery on deploy.
+ *
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [
+ *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],
+ *         policy: 'auth.user_id == node.owner' },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * Omitted sections leave the DB alone — partial adoption is explicitly
+ * supported. List-based sections (`resources`, `groups`, `relations`,
+ * `oauth`) are upserted and never auto-delete DB-only entries. Singleton
+ * sections (`registration`, `security`, `branding`) are replaced wholesale
+ * when declared.
+ */
+
+/**
+ * String value that may either be a literal secret or a reference to an
+ * environment variable on the **tenant** (resolved server-side at
+ * reconcile time, never shipped plaintext in the manifest).
+ *
+ * Accepted forms:
+ *   - `"literal-value"` — inline (not recommended for real secrets)
+ *   - `"${env.VAR_NAME}"` — string-template form
+ *   - `{ env: "VAR_NAME" }` — object form
+ */
+export type SecretRef = string | { env: string };
+
+// ── Resources + policies ──
+
+export interface ResourceDefinition {
+  /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */
+  name: string;
+  /** Human-readable title for the admin UI. */
+  title: string;
+  /** Optional longer description. */
+  description?: string;
+  /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */
+  actions: string[];
+  /**
+   * Optional raisin-rel policy expression. Evaluated on every KV/DB/
+   * realtime/media op that targets this resource. Leave empty to skip
+   * Layer 2 for this resource — tenant + owner isolation still applies.
+   */
+  policy?: string;
+}
+
+// ── Groups ──
+
+export interface GroupPermissionDefinition {
+  /** Must match a `ResourceDefinition.name`. */
+  resource_name: string;
+  /** Actions this group is granted on the resource. */
+  actions: string[];
+}
+
+export interface GroupDefinition {
+  /** Unique group name per tenant. */
+  name: string;
+  /** Optional description for the admin UI. */
+  description?: string;
+  /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */
+  permissions?: GroupPermissionDefinition[];
+}
+
+// ── Relations ──
+
+export interface RelationTypeDefinition {
+  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */
+  relation_name: string;
+  /** Human-readable title. */
+  title: string;
+  description?: string;
+  /** Grouping for the admin UI (e.g. `"family"`, `"work"`). */
+  category?: string;
+  icon?: string;
+  color?: string;
+  /** Name of the inverse relation type, if one exists. */
+  inverse_relation_name?: string;
+  /** When true, membership in this relation implies stewardship rights. */
+  implies_stewardship?: boolean;
+  /** When true, the relation can only target users flagged as minors. */
+  requires_minor?: boolean;
+  /** When true, the relation is symmetric (A→B implies B→A). */
+  bidirectional?: boolean;
+}
+
+// ── Registration fields ──
+
+export interface RegistrationFieldDefinition {
+  /** Field key used as the form field name + in profile data. */
+  key: string;
+  /** Display label. */
+  label: string;
+  /** One of: text, email, phone, date, number, select, boolean, url, textarea. */
+  field_type: string;
+  required: boolean;
+  show_on_register: boolean;
+  /** Optional validation metadata — passed through to the UI. */
+  validation?: Record<string, unknown>;
+}
+
+export interface RegistrationConfig {
+  /** Ordered list of custom registration fields. Declaring this replaces the full list. */
+  fields: RegistrationFieldDefinition[];
+}
+
+// ── OAuth providers ──
+
+export interface OAuthProviderDefinition {
+  enabled: boolean;
+  client_id: string;
+  /** Prefer `{ env: "VAR_NAME" }` or `"${env.VAR_NAME}"`. */
+  client_secret: SecretRef;
+  scopes: string[];
+  /** Only for `custom_oidc`. */
+  discovery_url?: string;
+}
+
+export interface OAuthProvidersConfig {
+  google?: OAuthProviderDefinition;
+  github?: OAuthProviderDefinition;
+  okta?: OAuthProviderDefinition;
+  custom_oidc?: OAuthProviderDefinition;
+}
+
+// ── Security ──
+
+export interface PasswordPolicyDefinition {
+  min_length: number;
+  require_uppercase: boolean;
+  require_number: boolean;
+  require_special: boolean;
+}
+
+export interface SessionConfigDefinition {
+  access_token_ttl_secs: number;
+  refresh_token_ttl_secs: number;
+  max_sessions_per_user: number;
+  require_email_verification: boolean;
+}
+
+export interface SecurityConfig {
+  password_policy?: PasswordPolicyDefinition;
+  session?: SessionConfigDefinition;
+}
+
+// ── Branding ──
+
+export interface BrandingConfig {
+  app_name?: string;
+  logo_url?: string;
+  primary_color?: string;
+  secondary_color?: string;
+  welcome_message?: string;
+  welcome_subtitle?: string;
+  /** `"centered"`, `"split-left"`, `"split-right"`, or `"fullscreen"`. */
+  layout?: string;
+  background_image_url?: string;
+  /** 0–100 percentage. */
+  background_focal_point?: { x: number; y: number };
+  background_gradient?: string;
+  /** `"light"`, `"dark"`, or `"auto"`. */
+  color_mode?: string;
+  font_family?: string;
+  terms_url?: string;
+  privacy_url?: string;
+  /** Raw CSS merged into the hosted auth pages. */
+  custom_css?: string;
+}
+
+// ── Top-level shape ──
+
+export interface AuthConfigBlock {
+  resources?: ResourceDefinition[];
+  groups?: GroupDefinition[];
+  relations?: RelationTypeDefinition[];
+  registration?: RegistrationConfig;
+  oauth?: OAuthProvidersConfig;
+  security?: SecurityConfig;
+  branding?: BrandingConfig;
+}
+
+export interface MaravillaConfig {
+  /** All project-level auth settings. Every field is optional — partial adoption is supported. */
+  auth?: AuthConfigBlock;
+}
+
+/**
+ * Identity function that returns the config unchanged — exists purely so the
+ * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense
+ * on every field.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],
+ *   },
+ * });
+ * ```
+ */
+export function defineConfig(config: MaravillaConfig): MaravillaConfig {
+  return config;
+}

package/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts'],
+  entry: ['src/index.ts', 'src/config.ts'],
   format: ['esm'],
   dts: true,
   splitting: false,