velocious 1.0.495 → 1.0.497

package/build/configuration-types.js

@@ -362,10 +362,31 @@
  * @property {FrontendModelResourceClassType} resourceClass - App sync resource class served by the auto-mounted sync endpoints.
  */
 
+/**
+ * Client-side sync transport owning HTTP POSTs to the framework sync endpoints,
+ * matching the frontend-model websocket client post contract.
+ * @typedef {object} VelociousSyncClientTransport
+ * @property {(path: string, body?: ?, options?: {headers?: Record<string, string>}) => Promise<{json: () => ?}>} post - Posts one request and resolves a response with a json accessor.
+ */
+
+/**
+ * Client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
+ * The framework owns the `${mountPath}/changes` and `${mountPath}/replay`
+ * POSTers over the given transport.
+ * @typedef {object} VelociousSyncClientConfiguration
+ * @property {() => string | Promise<string>} authenticationToken - Resolves the auth token sent with sync requests.
+ * @property {number} [batchSize] - Max syncs per request.
+ * @property {() => boolean | Promise<boolean>} [isOnline] - Connectivity gate for pulls and replays. Defaults to always online.
+ * @property {string} [mountPath] - Mount path the server serves the sync endpoints under (match the server's `sync.api.mountPath`). Defaults to "/velocious/sync"; normalization strips trailing slashes and always fills in the default.
+ * @property {(error: Error) => void} [onError] - Reports background replay/pull failures. Defaults to rethrowing.
+ * @property {VelociousSyncClientTransport} transport - Transport posting to the framework sync endpoints (e.g. the frontend-model websocket client).
+ */
+
 /**
  * Velocious sync configuration.
  * @typedef {object} VelociousSyncConfiguration
  * @property {VelociousSyncApiConfiguration} [api] - Auto-mounts the Velocious sync changes/replay endpoints for this resource class.
+ * @property {VelociousSyncClientConfiguration} [client] - Client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
  * @property {import("./sync/device-identity.js").SyncJsonWebKey | null} [deviceCertificateBackendPublicKey] - Public backend key used to verify offline device certificates for sync replay.
  * @property {number} [changeFeedRetentionSize] - Number of accepted server changes retained before clients must refresh from snapshot.
  * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.

package/build/configuration.js

@@ -444,12 +444,60 @@ export default class VelociousConfiguration {
     return {
       api: this._normalizeSyncApiConfiguration(api),
       changeFeedRetentionSize: changeFeedRetentionSize || 10000,
+      client: this._normalizeSyncClientConfiguration(sync?.client),
       deviceCertificateBackendPublicKey,
       offlineGrantSigningKeys: offlineGrantSigningKeys.map((key) => normalizeOfflineGrantSigningKey(key)),
       offlineGrantTtlMs: offlineGrantTtlMs || 24 * 60 * 60 * 1000
     }
   }
 
+  /**
+   * Normalizes client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
+   * @param {import("./configuration-types.js").VelociousSyncClientConfiguration | undefined} client - Client-side sync configuration.
+   * @returns {import("./configuration-types.js").VelociousSyncClientConfiguration | undefined} - Normalized client-side sync configuration.
+   */
+  _normalizeSyncClientConfiguration(client) {
+    if (client === undefined || client === null) return undefined
+
+    if (typeof client !== "object" || Array.isArray(client)) {
+      throw new Error("sync.client must be an object with transport and authenticationToken")
+    }
+
+    const {authenticationToken, batchSize, isOnline, mountPath, onError, transport, ...restClient} = client
+    const restClientKeys = Object.keys(restClient)
+
+    if (restClientKeys.length > 0) {
+      throw new Error(`sync.client received unknown keys: ${restClientKeys.join(", ")} (supported: authenticationToken, batchSize, isOnline, mountPath, onError, transport)`)
+    }
+    if (!transport || typeof transport !== "object" || typeof transport.post !== "function") {
+      throw new Error("sync.client.transport must be an object with a post(path, body) method (like the frontend-model websocket client)")
+    }
+    if (typeof authenticationToken !== "function") {
+      throw new Error("sync.client.authenticationToken must be a function resolving the auth token sent with sync requests")
+    }
+    if (isOnline !== undefined && typeof isOnline !== "function") {
+      throw new Error("sync.client.isOnline must be a function resolving connectivity")
+    }
+    if (onError !== undefined && typeof onError !== "function") {
+      throw new Error("sync.client.onError must be a function reporting background sync failures")
+    }
+    if (batchSize !== undefined && (!Number.isInteger(batchSize) || batchSize <= 0)) {
+      throw new Error("sync.client.batchSize must be a positive integer")
+    }
+    if (mountPath !== undefined && (typeof mountPath !== "string" || !mountPath.startsWith("/"))) {
+      throw new Error(`sync.client.mountPath must start with '/', got: ${String(mountPath)}`)
+    }
+
+    return {
+      authenticationToken,
+      batchSize,
+      isOnline,
+      mountPath: (mountPath || "/velocious/sync").replace(/\/+$/u, "") || "/",
+      onError,
+      transport
+    }
+  }
+
   /**
    * Normalizes sync API endpoint configuration.
    * @param {import("./configuration-types.js").VelociousSyncApiConfiguration | undefined} api - Sync API configuration.

package/build/database/column-types.js

@@ -0,0 +1,19 @@
+// @ts-check
+
+/**
+ * Driver column types that store boolean values. Drivers report storage types,
+ * which diverge for booleans (Postgres/SQLite `boolean`, some drivers `bool`,
+ * MSSQL `bit`), so cross-driver consumers must match them uniformly.
+ * @type {Set<string>}
+ */
+const BOOLEAN_COLUMN_TYPES = new Set(["bit", "bool", "boolean"])
+
+/**
+ * Whether a driver-reported (or cast) column type stores boolean values,
+ * uniformly across database drivers.
+ * @param {string} columnType - Driver-reported (or cast) column type.
+ * @returns {boolean} Whether the column type is boolean-backed.
+ */
+export function isBooleanColumnType(columnType) {
+  return BOOLEAN_COLUMN_TYPES.has(columnType.toLowerCase())
+}

package/build/database/record/index.js

@@ -48,6 +48,7 @@ import { normalizeDateStringForWrite, normalizeDateValueForRead, normalizeDateVa
 import {formatValue} from "../../utils/format-value.js"
 import {captureCreateAuditChanges, captureUpdateAuditChanges, createAudit, createCreateAudit, createDestroyAudit, createUpdateAudit, registerAuditCallback, registerAuditing, withoutAudit} from "./auditing.js"
 import ValidatorsFormat from "./validators/format.js"
+import ValidatorsLength from "./validators/length.js"
 import ValidatorsPresence from "./validators/presence.js"
 import ValidatorsUniqueness from "./validators/uniqueness.js"
 import registerActsAsListCallbacks from "./acts-as-list.js"
@@ -238,6 +239,15 @@ class VelociousDatabaseRecord {
    * @type {string | undefined} */
   static modelName
 
+  /**
+   * Opt-in client sync declaration consumed by `SyncClient.fromConfiguration(...)`.
+   * Declare `static sync = true` (all defaults) or a declaration object like
+   * `static sync = {track: ["create", "update"], syncType: "upsert"}` to have the
+   * sync client auto-discover this model and derive its resource config from
+   * column metadata.
+   * @type {import("../../sync/sync-client-types.js").ModelSyncDeclaration | undefined} */
+  static sync
+
   /**
    * Narrows the runtime value to the documented type.
    * @type {Promise<void> | null | undefined} */
@@ -4403,6 +4413,7 @@ class VelociousDatabaseRecord {
  */
 
 VelociousDatabaseRecord.registerValidatorType("format", ValidatorsFormat)
+VelociousDatabaseRecord.registerValidatorType("length", ValidatorsLength)
 VelociousDatabaseRecord.registerValidatorType("presence", ValidatorsPresence)
 VelociousDatabaseRecord.registerValidatorType("uniqueness", ValidatorsUniqueness)
 

package/build/database/record/validation-messages.js

@@ -0,0 +1,50 @@
+// @ts-check
+
+/**
+ * Translates a validation message ID into a localized message.
+ * @callback ValidationMessageTranslator
+ * @param {string} msgID - Stable message ID (e.g. "velocious.errors.messages.blank").
+ * @param {Record<string, string | number> & {defaultValue?: string}} [args] - Interpolation variables plus the English default message.
+ * @returns {string} Localized message.
+ */
+
+/**
+ * English default validation message predicates keyed by message type,
+ * matching Rails' `errors.messages.*` where an equivalent exists. Values may
+ * contain `%{variable}` placeholders.
+ * @type {Record<string, string>}
+ */
+export const VALIDATION_MESSAGE_DEFAULTS = {
+  blank: "can't be blank",
+  taken: "has already been taken",
+  too_long: "is too long (maximum is %{count} characters)",
+  too_short: "is too short (minimum is %{count} characters)"
+}
+
+/**
+ * Builds a validation message predicate through the framework's translation
+ * layer. The message is looked up under `velocious.errors.messages.<type>`
+ * with the English default as fallback; `%{variable}` placeholders are
+ * interpolated from the given variables. Without a translator the English
+ * default is interpolated directly.
+ * @param {object} args - Options.
+ * @param {ValidationMessageTranslator | null} [args.translator] - Translator resolving message IDs (usually `configuration.getTranslator()`).
+ * @param {string} args.type - Message type key in {@link VALIDATION_MESSAGE_DEFAULTS}.
+ * @param {Record<string, string | number>} [args.variables] - Interpolation variables.
+ * @returns {string} Localized message predicate.
+ */
+export default function validationMessage({translator, type, variables}) {
+  const defaultMessage = VALIDATION_MESSAGE_DEFAULTS[type]
+
+  if (!defaultMessage) throw new Error(`Unknown validation message type: ${String(type)}`)
+
+  if (translator) return translator(`velocious.errors.messages.${type}`, {...variables, defaultValue: defaultMessage})
+
+  let message = defaultMessage
+
+  for (const [variableName, variableValue] of Object.entries(variables ?? {})) {
+    message = message.replaceAll(`%{${variableName}}`, String(variableValue))
+  }
+
+  return message
+}

package/build/database/record/validators/length.js

@@ -0,0 +1,52 @@
+// @ts-check
+
+import Base from "./base.js"
+import validationMessage from "../validation-messages.js"
+
+export default class VelociousDatabaseRecordValidatorsLength extends Base {
+  /**
+   * Runs validate: bounds the value's string length by the `maximum` and/or
+   * `minimum` options. Absent values (null/undefined/"") are skipped — they
+   * are the presence validator's concern.
+   * @param {object} args - Options object.
+   * @param {import("../index.js").default} args.model - Model instance.
+   * @param {string} args.attributeName - Attribute name.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async validate({model, attributeName}) {
+    const maximum = this.args?.maximum
+    const minimum = this.args?.minimum
+
+    if (typeof maximum != "number" && typeof minimum != "number") {
+      throw new Error("length validator requires a maximum and/or minimum option")
+    }
+
+    const rawValue = model.readAttribute(attributeName)
+
+    if (rawValue === null || rawValue === undefined || rawValue === "") return
+
+    const valueLength = String(rawValue).length
+    const translator = model.getModelClass()._getConfiguration().getTranslator()
+
+    if (typeof maximum == "number" && valueLength > maximum) {
+      this._addError(model, attributeName, validationMessage({translator, type: "too_long", variables: {count: maximum}}))
+    }
+
+    if (typeof minimum == "number" && valueLength < minimum) {
+      this._addError(model, attributeName, validationMessage({translator, type: "too_short", variables: {count: minimum}}))
+    }
+  }
+
+  /**
+   * Adds a length validation error to the model.
+   * @param {import("../index.js").default} model - Model instance.
+   * @param {string} attributeName - Attribute name.
+   * @param {string} message - Translated message predicate.
+   * @returns {void}
+   */
+  _addError(model, attributeName, message) {
+    if (!(attributeName in model._validationErrors)) model._validationErrors[attributeName] = []
+
+    model._validationErrors[attributeName].push({type: "length", message})
+  }
+}

package/build/database/record/validators/presence.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import Base from "./base.js"
+import validationMessage from "../validation-messages.js"
 
 export default class VelociousDatabaseRecordValidatorsPresence extends Base {
   /**
@@ -16,7 +17,9 @@ export default class VelociousDatabaseRecordValidatorsPresence extends Base {
     if (!attributeValue) {
       if (!(attributeName in model._validationErrors)) model._validationErrors[attributeName] = []
 
-      model._validationErrors[attributeName].push({type: "presence", message: "can't be blank"})
+      const translator = model.getModelClass()._getConfiguration().getTranslator()
+
+      model._validationErrors[attributeName].push({type: "presence", message: validationMessage({translator, type: "blank"})})
     }
   }
 }

package/build/database/record/validators/uniqueness.js

@@ -2,6 +2,7 @@
 
 import Base from "./base.js"
 import * as inflection from "inflection"
+import validationMessage from "../validation-messages.js"
 
 export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
   /**
@@ -61,7 +62,9 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
     if (existingRecord) {
       if (!(attributeName in model._validationErrors)) model._validationErrors[attributeName] = []
 
-      model._validationErrors[attributeName].push({type: "uniqueness", message: "has already been taken"})
+      const translator = modelClass._getConfiguration().getTranslator()
+
+      model._validationErrors[attributeName].push({type: "uniqueness", message: validationMessage({translator, type: "taken"})})
     }
   }
 

package/build/frontend-model-resource/base-resource.js

@@ -3,6 +3,7 @@
 import AuthorizationBaseResource from "../authorization/base-resource.js"
 import * as inflection from "inflection"
 import isPlainObject from "../utils/plain-object.js"
+import VelociousError from "../velocious-error.js"
 
 /**
  * Built-in frontend-model resource action.
@@ -87,6 +88,34 @@ import isPlainObject from "../utils/plain-object.js"
  * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | import("../configuration-types.js").FrontendModelResourceConfiguration} [resourceConfiguration] - Optional normalized resource configuration.
  */
 
+/**
+ * Normalized sync replay mutation passed to the resource sync hooks.
+ * @typedef {import("../sync/sync-envelope-replay-service.js").SyncReplayMutation} FrontendModelSyncMutation
+ */
+
+/**
+ * Sync mutation authorization result.
+ * @typedef {object} FrontendModelSyncAuthorization
+ * @property {boolean} allowed - Whether the mutation may be applied.
+ * @property {string} [reason] - Stable failure reason code when denied.
+ */
+
+/**
+ * Arguments for the applySync full-escape-hatch hook.
+ * @typedef {object} FrontendModelApplySyncArgs
+ * @property {Record<string, ?>} context - Replay context.
+ * @property {import("../database/record/index.js").default | null} existingSync - Existing sync row or null.
+ * @property {FrontendModelSyncMutation} mutation - Normalized replay mutation.
+ */
+
+/**
+ * Apply result produced by routed sync mutation application.
+ * @typedef {object} FrontendModelSyncApplyResult
+ * @property {boolean} created - Whether a record was created.
+ * @property {boolean} [deleted] - Whether a record was deleted.
+ * @property {import("../database/record/index.js").default | null} record - Applied record or null.
+ */
+
 /**
  * Resolved frontend-model resource registration.
  * @typedef {object} FrontendModelResolvedResourceConfiguration
@@ -172,6 +201,16 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /** @type {?} */
   static SharedResource = undefined
 
+  /**
+   * Declarative writable-attribute permit list (camelCase attribute names)
+   * used as the default {@link FrontendModelBaseResource#permittedParams} and
+   * as the routed sync replay permit. Resolved through the shared resource
+   * like the other static resource config: an undeclared environment list
+   * falls back to the shared resource's list, while an explicit declaration
+   * (including `null`) wins.
+   * @type {string[] | null | undefined} */
+  static writableAttributes = undefined
+
   /**
    * Runs constructor.
    * @param {FrontendModelResourceAbilityArgs | FrontendModelResourceControllerArgs} args - Resource args.
@@ -206,7 +245,7 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
   /**
    * Reads a static resource config value from the environment resource first,
    * then from the shared resource.
-   * @param {"abilities" | "attachments" | "attributes" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "modelName" | "primaryKey" | "relationships" | "server" | "sync" | "translatedAttributes"} name - Static config property name.
+   * @param {"abilities" | "attachments" | "attributes" | "builtInCollectionCommands" | "builtInMemberCommands" | "collectionCommands" | "commands" | "memberCommands" | "modelName" | "primaryKey" | "relationships" | "server" | "sync" | "translatedAttributes" | "writableAttributes"} name - Static config property name.
    * @returns {?} - Resolved config value.
    */
   static sharedResourceStaticValue(name) {
@@ -481,9 +520,10 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
    *     }
    *   }
    *
-   * Default implementation returns `[]` — nothing permitted. Subclasses
-   * must override to enable writes. A resource that does not declare
-   * `permittedParams` cannot accept any write.
+   * Default implementation returns the declared
+   * {@link FrontendModelBaseResource.writableAttributes} permit list, or `[]`
+   * — nothing permitted — without a declared list. Subclasses override to
+   * customize; an explicit override always wins.
    * @param {{action?: "create" | "update", params?: Record<string, ?>, ability?: import("../authorization/ability.js").default, locals?: Record<string, ?>}} [arg] - Request context.
    * @returns {Array<string | Record<string, ?>>} - Permit spec.
    */
@@ -491,10 +531,140 @@ export default class FrontendModelBaseResource extends AuthorizationBaseResource
     return this.sharedResourceMethodOr("permittedParams", [arg], () => {
       void arg
 
-      return []
+      return this.declaredWritableAttributes() ?? []
     })
   }
 
+  /**
+   * Resolves the declared writable-attribute permit list from the environment
+   * resource first, then the shared resource — mirroring how the other
+   * static resource config resolves. An explicit environment declaration
+   * (including `null`) wins over the shared resource's list.
+   * @returns {string[] | null} Declared permit list or null when undeclared.
+   */
+  declaredWritableAttributes() {
+    const ResourceClass = /** @type {typeof FrontendModelBaseResource} */ (this.constructor)
+    const permittedAttributes = /** @type {string[] | null | undefined} */ (ResourceClass.sharedResourceStaticValue("writableAttributes"))
+
+    return permittedAttributes ?? null
+  }
+
+  /**
+   * Builds the client-safe error thrown for a failed writable-attribute validation.
+   * @param {string} message - Human-readable validation message.
+   * @param {{cause?: Error, code: string}} details - Stable machine-readable code and optional cause.
+   * @returns {Error} Client-safe error.
+   */
+  writableAttributeError(message, {cause, code}) {
+    return VelociousError.safe(message, cause ? {cause, code} : {code})
+  }
+
+  /**
+   * Authorizes one routed sync replay mutation before it is applied.
+   * Defaults to allowing every mutation; record-level authorization still
+   * applies through {@link FrontendModelBaseResource#findSyncRecord} scoping
+   * and the create membership check.
+   * @param {object} args - Options.
+   * @param {Record<string, ?>} args.context - Replay context.
+   * @param {FrontendModelSyncMutation} args.mutation - Normalized replay mutation.
+   * @returns {FrontendModelSyncAuthorization | Promise<FrontendModelSyncAuthorization>} Authorization result.
+   */
+  authorizeSyncMutation({context, mutation}) {
+    void context
+    void mutation
+
+    return {allowed: true}
+  }
+
+  /**
+   * Returns the per-sync failure reason reported when a routed sync mutation
+   * fails record-level authorization. Defaults to null, which reports the
+   * generic "access-denied" reason.
+   * @param {object} args - Options.
+   * @param {"create" | "destroy" | "update"} args.action - Denied action.
+   * @param {FrontendModelSyncMutation} args.mutation - Normalized replay mutation.
+   * @returns {string | null} Stable failure reason code or null for the generic default.
+   */
+  syncAuthorizationFailureReason({action, mutation}) {
+    void action
+    void mutation
+
+    return null
+  }
+
+  /**
+   * Finds the existing record targeted by a routed sync replay mutation.
+   * Defaults to an `accessibleFor` lookup by primary key through the
+   * resource's normalized ability action for update (or destroy for delete
+   * mutations), falling back to an unscoped lookup without an ability.
+   * @param {object} args - Options.
+   * @param {import("../authorization/ability.js").default} [args.ability] - Ability override. Defaults to the resource ability.
+   * @param {boolean} [args.forDelete] - Whether the lookup is for a delete mutation.
+   * @param {FrontendModelSyncMutation} args.mutation - Normalized replay mutation.
+   * @returns {Promise<import("../database/record/index.js").default | null>} Existing record or null.
+   */
+  async findSyncRecord({ability = this.ability, forDelete = false, mutation}) {
+    const ModelClass = this.modelClass()
+    const primaryKey = ModelClass.primaryKey()
+    const query = ability
+      ? ModelClass.accessibleFor(this.syncAbilityAction(forDelete ? "destroy" : "update"), ability)
+      : ModelClass.where({})
+
+    return await query.findBy({[primaryKey]: mutation.resourceId})
+  }
+
+  /**
+   * Maps a raw sync action to the resource's normalized ability action when
+   * the resource configuration declares an abilities mapping, otherwise the
+   * raw action name is used directly.
+   * @param {"create" | "destroy" | "update"} action - Raw sync action.
+   * @returns {string} Ability action.
+   */
+  syncAbilityAction(action) {
+    const abilities = this.resourceConfigurationValue?.abilities
+
+    if (abilities && typeof abilities == "object" && !Array.isArray(abilities)) {
+      const abilityAction = /** @type {Record<string, ?>} */ (abilities)[action]
+
+      if (typeof abilityAction == "string" && abilityAction.length > 0) return abilityAction
+    }
+
+    return action
+  }
+
+  /**
+   * Full escape hatch for routed sync mutation application. Returning a
+   * non-null result replaces the whole default apply flow (authorization,
+   * record lookup, normalization and save) with the returned apply result.
+   * @param {FrontendModelApplySyncArgs} args - Apply args.
+   * @returns {FrontendModelSyncApplyResult | null | Promise<FrontendModelSyncApplyResult | null>} Apply result or null for the default flow.
+   */
+  applySync(args) {
+    void args
+
+    return null
+  }
+
+  /**
+   * Runs after a routed sync mutation was applied. Returned entries are
+   * merged into the apply result, reaching persistExtraAttributes and
+   * broadcasts.
+   * @param {object} args - Options.
+   * @param {Record<string, ?>} args.context - Replay context.
+   * @param {boolean} args.created - Whether the record was created.
+   * @param {FrontendModelSyncMutation} args.mutation - Normalized replay mutation.
+   * @param {import("../database/record/index.js").default | null} args.record - Applied record or null.
+   * @returns {Record<string, ?> | Promise<Record<string, ?>>} Extra apply-result entries.
+   */
+  afterSyncApply({context, created, mutation, record}) {
+    void context
+    void created
+    void mutation
+    void record
+
+    return {}
+  }
+
   /**
    * Normalizes create attributes before permission filtering and saving.
    * @param {FrontendModelResourceAttributePayload} attributes - Incoming create attributes.

package/build/frontend-models/resource-definition.js

@@ -42,6 +42,7 @@ const RESOURCE_STATIC_CONFIG_KEYS = new Set([
   "primaryKey",
   "quickSearchColumns",
   "relationships",
+  "ReplayServiceClass",
   "server",
   "SharedResource",
   "sync",
@@ -881,3 +882,48 @@ function normalizeFrontendModelResourcePathForMatch(path) {
 
   return withLeadingSlash
 }
+
+/**
+ * Resolved frontend-model resource registration for a replay resource type.
+ * @typedef {object} FrontendModelResolvedResourceRegistration
+ * @property {string} modelName - Effective frontend model name (modelName override or registry key).
+ * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Registered resource class.
+ * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration} resourceConfiguration - Normalized resource configuration.
+ */
+
+/**
+ * Resolves the registered frontend-model resource class for a resource type
+ * across all backend projects. A resource's effective name is its
+ * `modelName` override when declared, otherwise its registry key — matching
+ * {@link frontendModelSyncManifestForBackendProjects}. A registry key shadowed
+ * by a `modelName` override does not resolve.
+ * @param {object} args - Options.
+ * @param {{getBackendProjects: () => import("../configuration-types.js").BackendProjectConfiguration[]}} args.configuration - Configuration exposing the backend projects.
+ * @param {string} args.resourceType - Frontend model name to resolve.
+ * @returns {FrontendModelResolvedResourceRegistration | null} Resolved registration or null when the resource type is not registered.
+ */
+export function resolveFrontendModelResourceClass({configuration, resourceType}) {
+  for (const backendProject of configuration.getBackendProjects()) {
+    const resources = frontendModelResourcesForBackendProject(backendProject)
+
+    for (const configuredModelName of Object.keys(resources)) {
+      const resourceDefinition = resources[configuredModelName]
+      const resourceClass = frontendModelResourceClassFromDefinition(resourceDefinition)
+
+      if (!resourceClass) continue
+
+      // Cheap direct-key mismatch skip: only normalize configurations for the
+      // matching key or when a modelName override could rename the resource.
+      if (configuredModelName !== resourceType && !resourceClass.sharedResourceStaticValue("modelName")) continue
+
+      const resourceConfiguration = frontendModelResourceConfigurationFromDefinition(resourceDefinition)
+
+      if (!resourceConfiguration) continue
+      if ((resourceConfiguration.modelName || configuredModelName) !== resourceType) continue
+
+      return {modelName: resourceType, resourceClass, resourceConfiguration}
+    }
+  }
+
+  return null
+}

package/build/src/configuration-types.d.ts

@@ -315,10 +315,29 @@
  * @property {string} [mountPath] - Mount path for the sync endpoints. Defaults to "/velocious/sync".
  * @property {FrontendModelResourceClassType} resourceClass - App sync resource class served by the auto-mounted sync endpoints.
  */
+/**
+ * Client-side sync transport owning HTTP POSTs to the framework sync endpoints,
+ * matching the frontend-model websocket client post contract.
+ * @typedef {object} VelociousSyncClientTransport
+ * @property {(path: string, body?: ?, options?: {headers?: Record<string, string>}) => Promise<{json: () => ?}>} post - Posts one request and resolves a response with a json accessor.
+ */
+/**
+ * Client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
+ * The framework owns the `${mountPath}/changes` and `${mountPath}/replay`
+ * POSTers over the given transport.
+ * @typedef {object} VelociousSyncClientConfiguration
+ * @property {() => string | Promise<string>} authenticationToken - Resolves the auth token sent with sync requests.
+ * @property {number} [batchSize] - Max syncs per request.
+ * @property {() => boolean | Promise<boolean>} [isOnline] - Connectivity gate for pulls and replays. Defaults to always online.
+ * @property {string} [mountPath] - Mount path the server serves the sync endpoints under (match the server's `sync.api.mountPath`). Defaults to "/velocious/sync"; normalization strips trailing slashes and always fills in the default.
+ * @property {(error: Error) => void} [onError] - Reports background replay/pull failures. Defaults to rethrowing.
+ * @property {VelociousSyncClientTransport} transport - Transport posting to the framework sync endpoints (e.g. the frontend-model websocket client).
+ */
 /**
  * Velocious sync configuration.
  * @typedef {object} VelociousSyncConfiguration
  * @property {VelociousSyncApiConfiguration} [api] - Auto-mounts the Velocious sync changes/replay endpoints for this resource class.
+ * @property {VelociousSyncClientConfiguration} [client] - Client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
  * @property {import("./sync/device-identity.js").SyncJsonWebKey | null} [deviceCertificateBackendPublicKey] - Public backend key used to verify offline device certificates for sync replay.
  * @property {number} [changeFeedRetentionSize] - Number of accepted server changes retained before clients must refresh from snapshot.
  * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.
@@ -1255,6 +1274,51 @@ export type VelociousSyncApiConfiguration = {
      */
     resourceClass: FrontendModelResourceClassType;
 };
+/**
+ * Client-side sync transport owning HTTP POSTs to the framework sync endpoints,
+ * matching the frontend-model websocket client post contract.
+ */
+export type VelociousSyncClientTransport = {
+    /**
+     * - Posts one request and resolves a response with a json accessor.
+     */
+    post: (path: string, body?: unknown, options?: {
+        headers?: Record<string, string>;
+    }) => Promise<{
+        json: () => unknown;
+    }>;
+};
+/**
+ * Client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
+ * The framework owns the `${mountPath}/changes` and `${mountPath}/replay`
+ * POSTers over the given transport.
+ */
+export type VelociousSyncClientConfiguration = {
+    /**
+     * - Resolves the auth token sent with sync requests.
+     */
+    authenticationToken: () => string | Promise<string>;
+    /**
+     * - Max syncs per request.
+     */
+    batchSize?: number | undefined;
+    /**
+     * - Connectivity gate for pulls and replays. Defaults to always online.
+     */
+    isOnline?: (() => boolean | Promise<boolean>) | undefined;
+    /**
+     * - Mount path the server serves the sync endpoints under (match the server's `sync.api.mountPath`). Defaults to "/velocious/sync"; normalization strips trailing slashes and always fills in the default.
+     */
+    mountPath?: string | undefined;
+    /**
+     * - Reports background replay/pull failures. Defaults to rethrowing.
+     */
+    onError?: ((error: Error) => void) | undefined;
+    /**
+     * - Transport posting to the framework sync endpoints (e.g. the frontend-model websocket client).
+     */
+    transport: VelociousSyncClientTransport;
+};
 /**
  * Velocious sync configuration.
  */
@@ -1263,6 +1327,10 @@ export type VelociousSyncConfiguration = {
      * - Auto-mounts the Velocious sync changes/replay endpoints for this resource class.
      */
     api?: VelociousSyncApiConfiguration | undefined;
+    /**
+     * - Client-side sync configuration consumed by `SyncClient.fromConfiguration(...)`.
+     */
+    client?: VelociousSyncClientConfiguration | undefined;
     /**
      * - Public backend key used to verify offline device certificates for sync replay.
      */