npm - @gaganref/confect-core - Versions diffs - 10.3.1-fork.8 → 10.3.1-fork.81 - Mend

@gaganref/confect-core 10.3.1-fork.8 → 10.3.1-fork.81

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (89) hide show

package/dist/ActionCall.d.ts +18 -0
package/dist/ActionCall.d.ts.map +1 -0
package/dist/ActionCall.js +21 -0
package/dist/ActionCall.js.map +1 -0
package/dist/App.d.ts +30 -93
package/dist/App.d.ts.map +1 -1
package/dist/App.js +24 -38
package/dist/App.js.map +1 -1
package/dist/Auth.d.ts +33 -9
package/dist/Auth.d.ts.map +1 -1
package/dist/Auth.js +17 -2
package/dist/Auth.js.map +1 -1
package/dist/Callback.d.ts +7 -2
package/dist/Callback.d.ts.map +1 -1
package/dist/Callback.js +11 -6
package/dist/Callback.js.map +1 -1
package/dist/Component.d.ts +98 -2
package/dist/Component.d.ts.map +1 -1
package/dist/Component.js +44 -18
package/dist/Component.js.map +1 -1
package/dist/FunctionSpec.d.ts +365 -2
package/dist/FunctionSpec.d.ts.map +1 -1
package/dist/FunctionSpec.js +66 -3
package/dist/FunctionSpec.js.map +1 -1
package/dist/GenericId.js +2 -2
package/dist/GroupSpec.js +1 -1
package/dist/Http.d.ts +4 -8
package/dist/Http.d.ts.map +1 -1
package/dist/Http.js +15 -22
package/dist/Http.js.map +1 -1
package/dist/ManifestSection.d.ts +70 -0
package/dist/ManifestSection.d.ts.map +1 -0
package/dist/ManifestSection.js +7 -0
package/dist/ManifestSection.js.map +1 -0
package/dist/Mount.d.ts +200 -0
package/dist/Mount.d.ts.map +1 -0
package/dist/Mount.js +116 -0
package/dist/Mount.js.map +1 -0
package/dist/PaginationError.js +1 -1
package/dist/Profile.d.ts +95 -0
package/dist/Profile.d.ts.map +1 -0
package/dist/Profile.js +15 -0
package/dist/Profile.js.map +1 -0
package/dist/Ref.d.ts +4 -3
package/dist/Ref.d.ts.map +1 -1
package/dist/Ref.js +13 -19
package/dist/Ref.js.map +1 -1
package/dist/RefInternal.d.ts +3 -0
package/dist/RefInternal.d.ts.map +1 -0
package/dist/RefInternal.js +16 -0
package/dist/RefInternal.js.map +1 -0
package/dist/SchemaToValidator.d.ts +11 -2
package/dist/SchemaToValidator.d.ts.map +1 -1
package/dist/SchemaToValidator.js +43 -14
package/dist/SchemaToValidator.js.map +1 -1
package/dist/SystemFields.js +3 -3
package/dist/Table.d.ts +48 -9
package/dist/Table.d.ts.map +1 -1
package/dist/Table.js +41 -13
package/dist/Table.js.map +1 -1
package/dist/index.d.ts +4 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +10 -6
package/dist/internal/annotations.d.ts +2 -0
package/dist/internal/annotations.d.ts.map +1 -0
package/dist/internal/annotations.js +6 -0
package/dist/internal/annotations.js.map +1 -0
package/dist/internal/scalarDocs.d.ts +5 -0
package/dist/internal/scalarDocs.d.ts.map +1 -0
package/dist/internal/scalarDocs.js +43 -0
package/dist/internal/scalarDocs.js.map +1 -0
package/package.json +3 -3
package/src/ActionCall.ts +25 -0
package/src/App.ts +36 -136
package/src/Auth.ts +54 -11
package/src/Callback.ts +17 -4
package/src/Component.ts +196 -11
package/src/FunctionSpec.ts +566 -5
package/src/Http.ts +15 -37
package/src/ManifestSection.ts +78 -0
package/src/Mount.ts +401 -0
package/src/Profile.ts +141 -0
package/src/Ref.ts +19 -26
package/src/RefInternal.ts +26 -0
package/src/SchemaToValidator.ts +47 -5
package/src/Table.ts +157 -23
package/src/index.ts +4 -0
package/src/internal/annotations.ts +1 -0
package/src/internal/scalarDocs.ts +72 -0

package/dist/internal/scalarDocs.js ADDED Viewed

@@ -0,0 +1,43 @@
+import * as Effect from "effect/Effect";
+import * as HttpRouter from "effect/http/HttpRouter";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import * as OpenApi from "effect/http-api/OpenApi";
+//#region src/internal/scalarDocs.ts
+const escape = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+const escapeAttribute = (value) => escape(value).replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
+const escapeJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c").replaceAll("\u2028", "\\u2028").replaceAll("\u2029", "\\u2029");
+const scalarDocs = (api, path) => HttpRouter.use((router) => {
+	let response;
+	return router.add("GET", path, Effect.sync(() => {
+		if (response !== void 0) return response;
+		const spec = OpenApi.fromApi(api);
+		const description = (tag) => !spec.info.description ? "" : `<meta name="${tag}" content="${escapeAttribute(spec.info.description)}"/>`;
+		response = HttpServerResponse.html(`<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>${escape(spec.info.title)}</title>
+    ${description("description")}
+    ${description("og:description")}
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="api-reference-container"></div>
+    <script src="${escapeAttribute("https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest/dist/browser/standalone.min.js")}" crossorigin><\/script>
+    <script>
+      window.Scalar.createApiReference(document.getElementById('api-reference-container'), {
+        ...${escapeJson({ _integration: "html" })},
+        content: ${escapeJson(spec)}
+      })
+    <\/script>
+  </body>
+</html>`);
+		return response;
+	}));
+});
+//#endregion
+export { scalarDocs };
+//# sourceMappingURL=scalarDocs.js.map

package/dist/internal/scalarDocs.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"scalarDocs.js","names":[],"sources":["../../src/internal/scalarDocs.ts"],"sourcesContent":["import * as Effect from \"effect/Effect\";\nimport * as HttpRouter from \"effect/http/HttpRouter\";\nimport * as HttpServerResponse from \"effect/http/HttpServerResponse\";\nimport type * as HttpApi from \"effect/http-api/HttpApi\";\nimport type * as HttpApiGroup from \"effect/http-api/HttpApiGroup\";\nimport * as OpenApi from \"effect/http-api/OpenApi\";\n\nconst escape = (value: string) =>\n value\n .replaceAll(\"&\", \"&\")\n .replaceAll(\"<\", \"<\")\n .replaceAll(\">\", \">\");\n\nconst escapeAttribute = (value: string) =>\n escape(value).replaceAll('\"', \""\").replaceAll(\"'\", \"'\");\n\nconst escapeJson = (value: unknown) =>\n JSON.stringify(value)\n .replaceAll(\"<\", \"\\\\u003c\")\n .replaceAll(\"\\u2028\", \"\\\\u2028\")\n .replaceAll(\"\\u2029\", \"\\\\u2029\");\n\n// WORKAROUND: Effect 4.0.6's HttpApiScalar module imports its inline Scalar\n// script dynamically, and Convex's bundler then splits a schema that reaches it\n// into an imported chunk, which Convex refuses. This copies `layerCdn`'s page\n// byte for byte. Remove when `checkSchemaBundle.mjs` passes with\n// `HttpApiScalar.layerCdn` restored.\nexport const scalarDocs = <\n Id extends string,\n Groups extends HttpApiGroup.Constraint,\n>(\n api: HttpApi.HttpApi<Id, Groups>,\n path: `/${string}`,\n) =>\n HttpRouter.use((router) => {\n let response: HttpServerResponse.HttpServerResponse | undefined;\n return router.add(\n \"GET\",\n path,\n Effect.sync(() => {\n if (response !== undefined) return response;\n const spec = OpenApi.fromApi(api);\n const description = (tag: string) =>\n !spec.info.description\n ? \"\"\n : `<meta name=\"${tag}\" content=\"${escapeAttribute(spec.info.description)}\"/>`;\n response = HttpServerResponse.html(`<!doctype html>\n<html>\n <head>\n <meta charset=\"utf-8\" />\n <title>${escape(spec.info.title)}</title>\n ${description(\"description\")}\n ${description(\"og:description\")}\n <meta\n name=\"viewport\"\n content=\"width=device-width, initial-scale=1\" />\n </head>\n <body>\n <div id=\"api-reference-container\"></div>\n <script src=\"${escapeAttribute(\"https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest/dist/browser/standalone.min.js\")}\" crossorigin></script>\n <script>\n window.Scalar.createApiReference(document.getElementById('api-reference-container'), {\n ...${escapeJson({ _integration: \"html\" })},\n content: ${escapeJson(spec)}\n })\n </script>\n </body>\n</html>`);\n return response;\n }),\n );\n });\n"],"mappings":";;;;;AAOA,MAAM,UAAU,UACd,MACG,WAAW,KAAK,OAAO,CAAC,CACxB,WAAW,KAAK,MAAM,CAAC,CACvB,WAAW,KAAK,MAAM;AAE3B,MAAM,mBAAmB,UACvB,OAAO,KAAK,CAAC,CAAC,WAAW,MAAK,QAAQ,CAAC,CAAC,WAAW,KAAK,OAAO;AAEjE,MAAM,cAAc,UAClB,KAAK,UAAU,KAAK,CAAC,CAClB,WAAW,KAAK,SAAS,CAAC,CAC1B,WAAW,UAAU,SAAS,CAAC,CAC/B,WAAW,UAAU,SAAS;AAOnC,MAAa,cAIX,KACA,SAEA,WAAW,KAAK,WAAW;CACzB,IAAI;CACJ,OAAO,OAAO,IACZ,OACA,MACA,OAAO,WAAW;EAChB,IAAI,aAAa,KAAA,GAAW,OAAO;EACnC,MAAM,OAAO,QAAQ,QAAQ,GAAG;EAChC,MAAM,eAAe,QACnB,CAAC,KAAK,KAAK,cACP,KACA,eAAe,IAAI,aAAa,gBAAgB,KAAK,KAAK,WAAW,EAAE;EAC7E,WAAW,mBAAmB,KAAK;;;;aAI9B,OAAO,KAAK,KAAK,KAAK,EAAE;MAC/B,YAAY,aAAa,EAAE;MAC3B,YAAY,gBAAgB,EAAE;;;;;;;mBAOjB,gBAAgB,0FAA0F,EAAE;;;aAGlH,WAAW,EAAE,cAAc,OAAO,CAAC,EAAE;mBAC/B,WAAW,IAAI,EAAE;;;;QAI5B;EACA,OAAO;CACT,CAAC,CACH;AACF,CAAC"}

package/package.json CHANGED Viewed

@@ -1,9 +1,9 @@
 {
   "name": "@gaganref/confect-core",
-  "version": "10.3.1-fork.8",
+  "version": "10.3.1-fork.81",
   "peerDependencies": {
-    "convex": "^1.46.0",
-    "effect": "^4.0.0"
+    "convex": "^1.49.0",
+    "effect": ">=4.0.0 <4.1.0"
   },
   "description": "Shared specs and schemas used by all Confect packages",
   "author": "RJ Dellecese",

package/src/ActionCall.ts ADDED Viewed

@@ -0,0 +1,25 @@
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+import type * as Schema from "effect/Schema";
+import * as FunctionSpec from "./FunctionSpec.js";
+import * as MiddlewareSpec from "./MiddlewareSpec.js";
+import type * as Ref from "./Ref.js";
+export interface Call {
+  <Target extends Ref.AnyQuery | Ref.AnyMutation>(
+    target: Target,
+    ...args: Ref.OptionalArgs<NoInfer<Target>>
+  ): Effect.Effect<Ref.Returns<Target>, Ref.Error<Target> | Schema.SchemaError>;
+}
+export class ActionCall extends Context.Service<ActionCall, Call>()(
+  "@confect/core/ActionCall",
+) {}
+export class Middleware extends MiddlewareSpec.MiddlewareSpec<
+  Middleware,
+  { provides: ActionCall }
+>()("@confect/core/ActionCall/Middleware", {
+  functionTypes: { query: false, mutation: false, action: true },
+}) {}
+export const profile = FunctionSpec.extend()({ middleware: [Middleware] });

package/src/App.ts CHANGED Viewed

@@ -1,11 +1,11 @@
-import type { ComponentDefinition, EnvDefinition } from "convex/server";
-import type { Infer, Validator } from "convex/values";
+import type { ComponentDefinition } from "convex/server";
 import type * as HttpApi from "effect/http-api/HttpApi";
 import * as Predicate from "effect/Predicate";
 import type * as Env from "./Env.js";
+import type * as MiddlewareSpec from "./MiddlewareSpec.js";
+import * as Mount from "./Mount.js";
 const TypeId = "~@confect/core/App";
-const MountTypeId = "~@confect/core/App/Mount";
 /**
  * The default export of a Convex component's `convex.config` module.
@@ -19,112 +19,11 @@ export type HttpPrefix = `/${string}`;
  */
 export type Api = HttpApi.HttpApi<string, any>;
-type EnvOf<D extends Definition> = D["__env"];
-type IsOptional<V> = V extends Validator<any, "optional", any> ? true : false;
-type RequiredKeys<E extends EnvDefinition> = {
-  [K in keyof E]: IsOptional<E[K]> extends true ? never : K;
-}[keyof E];
-type SlotValue<V extends Validator<any, any, any>> = Extract<Infer<V>, string>;
-/**
- * What one component env slot accepts: a constant, or an entry whose Convex
- * value fits. A required slot takes only a required entry.
- */
-type Slot<V extends Validator<any, any, any>> =
-  IsOptional<V> extends true
-    ? SlotValue<V> | undefined | Env.Entry<string, any, SlotValue<V>, boolean>
-    : SlotValue<V> | Env.Entry<string, any, SlotValue<V>, false>;
-export type Bindings<E extends EnvDefinition> = {
-  readonly [K in RequiredKeys<E>]: Slot<E[K]>;
-} & {
-  readonly [K in Exclude<keyof E, RequiredKeys<E>>]?: Slot<E[K]>;
-};
-type HttpOptions =
-  | { readonly httpPrefix?: never; readonly api?: never }
-  | { readonly httpPrefix: HttpPrefix; readonly api?: Api };
-export type Options<D extends Definition> = HttpOptions &
-  ([RequiredKeys<EnvOf<D>>] extends [never]
-    ? { readonly env?: Bindings<EnvOf<D>> }
-    : { readonly env: Bindings<EnvOf<D>> });
-type Exact<D extends Definition, O> = {
-  readonly [K in Exclude<keyof O, "env" | "httpPrefix" | "api">]: never;
-} & (O extends { readonly env: infer B }
-  ? {
-      readonly env: { readonly [K in Exclude<keyof B, keyof EnvOf<D>>]: never };
-    }
-  : unknown);
-export interface MountData {
-  readonly definition: Definition;
-  readonly httpPrefix: HttpPrefix | undefined;
-  readonly api: Api | undefined;
-  readonly env: Readonly<Record<string, string | Env.AnyEntry | undefined>>;
-}
-/**
- * A mounted Convex component. `O` keeps the options as written, so {@link make}
- * can see which backends the bound entries come from.
- */
-export interface Mount<out D extends Definition, out O> extends MountData {
-  readonly [MountTypeId]: { readonly definition: D; readonly options: O };
-  readonly httpPrefix: O extends {
-    readonly httpPrefix: infer P extends HttpPrefix;
-  }
-    ? P
-    : undefined;
-}
-export type AnyMount = Mount<Definition, unknown>;
-/**
- * Mount a Convex component: the default export of its `convex.config` module,
- * official or Confect-authored. `env` is typed against the component's own
- * `defineComponent({ env })` declaration, so a missing required binding, an
- * optional entry in a required slot, a wrong literal and an unknown slot fail
- * to typecheck. `api` is the component's `HttpApi`, for route checks.
- */
-export function mount<const D extends Definition>(
-  definition: D &
-    ([RequiredKeys<EnvOf<D>>] extends [never]
-      ? unknown
-      : "App.mount: this component declares required env; pass { env }"),
-): Mount<D, {}>;
-export function mount<const D extends Definition, const O extends Options<D>>(
-  definition: D,
-  options: O & Exact<NoInfer<D>, NoInfer<O>>,
-): Mount<D, O>;
-export function mount(
-  definition: Definition,
-  options?: {
-    readonly httpPrefix?: HttpPrefix;
-    readonly api?: Api;
-    readonly env?: MountData["env"];
-  },
-): AnyMount {
-  return {
-    [MountTypeId]: { definition, options },
-    definition,
-    httpPrefix: options?.httpPrefix,
-    api: options?.api,
-    env: options?.env ?? {},
-    // The overloads above carry the precise types; this body serves both.
-  } as AnyMount;
-}
 type OwnerOf<V> = V extends Env.Entry<infer N, any, any, any> ? N : never;
 type Owners<M> =
-  M extends Mount<Definition, infer O>
-    ? O extends { readonly env: infer B }
-      ? { [K in keyof B]: OwnerOf<B[K]> }[keyof B]
-      : never
+  M extends Mount.Mount<any, any, Mount.Declared<any, infer B>>
+    ? { [K in keyof B]: OwnerOf<B[K]> }[keyof B]
     : never;
 type OwnedBy<N extends string, M> = {
@@ -137,51 +36,57 @@ export type Kind = "app" | "component";
 export interface App<
   E extends Env.Any,
-  M extends Readonly<Record<string, AnyMount>>,
+  M extends ReadonlyArray<Mount.Any>,
   K extends Kind = Kind,
 > {
   readonly [TypeId]: typeof TypeId;
   readonly kind: K;
   readonly env: E;
+  readonly components: ReadonlyArray<Definition>;
   readonly mounts: M;
+  readonly requiresMiddleware: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
 }
-export type Any = App<Env.Any, Readonly<Record<string, AnyMount>>>;
+export type Any = App<Env.Any, ReadonlyArray<Mount.Any>>;
 /**
- * Declare a backend, in `confect/app.ts`: its env and its mounted Convex
- * components by name. Set `kind: "component"` when declaring a component; the
- * default is `"app"`. Codegen rejects a kind that differs from its target.
- * Codegen writes `convex/convex.config.ts` from it. A mount that binds another
- * backend's env entry fails to typecheck.
+ * Declare a backend, in `confect/app.ts`: its env, the `convex.config`
+ * definitions of the Convex components it mounts, and its mounts. Set `kind:
+ * "component"` when declaring a component; the default is `"app"`. Codegen
+ * rejects a kind that differs from its target, and writes
+ * `convex/convex.config.ts` with one `app.use` per mount, in list order, using
+ * the definition whose `defineComponent` name is the mount's component name. A
+ * mount that binds another backend's env entry fails to typecheck.
  *
  * ```ts
+ * import email from "@acme/email/convex.config";
+ * import workpool from "@convex-dev/workpool/convex.config";
+ *
  * export default App.make({
  *   env,
- *   mounts: {
- *     email: App.mount(email, {
- *       httpPrefix: "/email",
- *       env: { FROM: env.EMAIL_FROM, KEY: env.RESEND_API_KEY },
- *     }),
- *     importsPool: App.mount(workpool),
- *   },
+ *   components: [email, workpool],
+ *   mounts: [BulkEmail, TransactionalEmail, ImportsPool],
  * });
  * ```
  */
 export const make = <
   const E extends Env.Any,
-  const M extends Readonly<Record<string, AnyMount>> = {},
+  const M extends ReadonlyArray<Mount.Any> = [],
   const K extends Kind = "app",
 >(
   options: {
     readonly env: E;
+    readonly requiresMiddleware?: ReadonlyArray<MiddlewareSpec.AnyMiddlewareSpec>;
+    readonly components?: ReadonlyArray<Definition>;
     readonly mounts?: M & OwnedBy<NoInfer<Env.Name<E>>, NoInfer<M>>;
   } & ([K] extends ["app"] ? { readonly kind?: K } : { readonly kind: K }),
 ): App<E, M, K> => ({
   [TypeId]: TypeId,
   kind: options.kind ?? ("app" as K),
   env: options.env,
-  mounts: options.mounts ?? ({} as M),
+  components: options.components ?? [],
+  mounts: options.mounts ?? ([] as unknown as M),
+  requiresMiddleware: options.requiresMiddleware ?? [],
 });
 export const isApp = (u: unknown): u is Any =>
@@ -190,21 +95,16 @@ export const isApp = (u: unknown): u is Any =>
   Predicate.hasProperty(u, "kind") &&
   (u.kind === "app" || u.kind === "component");
-export const isMount = (u: unknown): u is AnyMount =>
-  Predicate.hasProperty(u, MountTypeId);
 export const env = <A extends Any>(app: A): A["env"] => app.env;
 /**
- * Every mount with its name, in declaration order.
+ * The `convex.config` definitions the backend lists, in list order.
+ */
+export const components = (app: Any): ReadonlyArray<Definition> =>
+  app.components;
+/**
+ * What each mount was declared with, in list order.
  */
-export const mounts = (
-  app: Any,
-): ReadonlyArray<MountData & { readonly name: string }> =>
-  Object.entries(app.mounts).map(([name, installed]) => ({
-    name,
-    definition: installed.definition,
-    httpPrefix: installed.httpPrefix,
-    api: installed.api,
-    env: installed.env,
-  }));
+export const mounts = (app: Any): ReadonlyArray<Mount.Data> =>
+  app.mounts.map(Mount.data);

package/src/Auth.ts CHANGED Viewed

@@ -1,9 +1,12 @@
 import type { AuthProvider } from "convex/server";
 import * as Predicate from "effect/Predicate";
 import type * as App from "./App.js";
+import type * as Env from "./Env.js";
+import * as Mount from "./Mount.js";
 import type { TypeError } from "./Types.js";
 const TypeId = "~@confect/core/Auth";
+const CloudUrlTypeId = "~@confect/core/Auth/CloudUrl";
 const SiteUrlTypeId = "~@confect/core/Auth/SiteUrl";
 /**
@@ -15,19 +18,59 @@ export interface SiteUrl {
   readonly path: string;
 }
-type Url = string | SiteUrl;
+/**
+ * The deployment's cloud URL (`CONVEX_CLOUD_URL`) plus a path.
+ */
+export interface CloudUrl {
+  readonly [CloudUrlTypeId]: typeof CloudUrlTypeId;
+  readonly path: string;
+}
-type WithSiteUrl<P> = P extends unknown
+type Url =
+  | string
+  | SiteUrl
+  | CloudUrl
+  | Env.Entry<string, string, string, false>;
+type WithUrls<P> = P extends unknown
   ? {
-      [K in keyof P]: K extends "domain" | "issuer" | "jwks" ? Url : P[K];
+      [K in keyof P]: K extends "domain" | "issuer" | "jwks" | "applicationID"
+        ? Url
+        : P[K];
     }
   : never;
 /**
- * Convex's `AuthProvider`, with `domain`, `issuer` and `jwks` also taking a
- * {@link SiteUrl}.
+ * Convex's provider list with deployment URLs and required, public env strings.
+ */
+export type Provider = WithUrls<AuthProvider> & {
+  /**
+   * Application-defined token family, copied to the runtime provider data.
+   */
+  readonly family?: string;
+  /**
+   * Application-defined issuer name, for example a trusted service.
+   */
+  readonly name?: string;
+};
+/**
+ * The cloud URL, or a path under it, resolved when Convex loads auth config.
  */
-export type Provider = WithSiteUrl<AuthProvider>;
+export const cloudUrl = (path: `/${string}` | "" = ""): CloudUrl => ({
+  [CloudUrlTypeId]: CloudUrlTypeId,
+  path,
+});
+/**
+ * The path of a cloud URL placeholder, or `undefined` for another value.
+ */
+export const cloudUrlPath = (u: unknown): string | undefined =>
+  Predicate.hasProperty(u, CloudUrlTypeId) &&
+  Predicate.hasProperty(u, "path") &&
+  typeof u.path === "string"
+    ? u.path
+    : undefined;
 export interface Auth<A extends App.Any> {
   readonly [TypeId]: typeof TypeId;
@@ -43,19 +86,19 @@ export type Any = Auth<App.Any>;
  */
 export function siteUrl(path?: `/${string}`): SiteUrl;
 export function siteUrl(
-  mount: { readonly httpPrefix: App.HttpPrefix },
+  mount: Mount.Mount<any, string, Mount.Declared<App.HttpPrefix>>,
   path?: `/${string}`,
 ): SiteUrl;
 export function siteUrl(
-  pathOrMount?: `/${string}` | { readonly httpPrefix: App.HttpPrefix },
+  pathOrMount?: `/${string}` | Mount.Any,
   path: string = "",
 ): SiteUrl {
   return {
     [SiteUrlTypeId]: SiteUrlTypeId,
     path:
-      typeof pathOrMount === "object"
-        ? pathOrMount.httpPrefix.replace(/\/+$/, "") + path
-        : (pathOrMount ?? ""),
+      typeof pathOrMount === "string" || pathOrMount === undefined
+        ? (pathOrMount ?? "")
+        : (Mount.data(pathOrMount).httpPrefix ?? "").replace(/\/+$/, "") + path,
   };
 }

package/src/Callback.ts CHANGED Viewed

@@ -8,6 +8,8 @@ import * as Schema from "effect/Schema";
 import * as SchemaGetter from "effect/SchemaGetter";
 import * as FunctionProvenance from "./FunctionProvenance.js";
 import * as Ref from "./Ref.js";
+import { getFunctionReference } from "./RefInternal.js";
+import { CallbackContract } from "./internal/annotations.js";
 import type * as RuntimeAndFunctionType from "./RuntimeAndFunctionType.js";
 export const TypeId = "~@confect/core/Callback";
@@ -137,6 +139,7 @@ const isHandleOf =
 const fromText = <Contract_ extends Any>(
   contract: Contract_,
   text: string,
+  reservedArgument?: string,
 ): Handle<Contract_> =>
   Object.assign(
     Ref.fromProvenance(
@@ -145,25 +148,35 @@ const fromText = <Contract_ extends Any>(
       [],
       // Convex types a handle as a string that is also a function reference.
       text as unknown as FunctionReference<any, any>,
+      contract.functionType,
+      contract.functionType === "query" ? undefined : reservedArgument,
     ),
     { [HandleTypeId]: contract.id },
   ) as unknown as Handle<Contract_>;
 /**
  * The schema of a handle for `contract`: a string on the wire, a runnable ref
- * once decoded. Use it in a component's function args or tables.
+ * once decoded. Use it in a component's function args or tables. It lowers to
+ * Convex's `v.function` with the contract's encoded args and returns.
+ * `reservedArgument` opts mutation and action handles into context forwarding.
+ * The host target must reserve the same argument name.
  */
 export const handle = <Contract_ extends Any>(
   contract: Contract_,
+  options?: {
+    readonly reservedArgument?: Contract_["functionType"] extends "query"
+      ? never
+      : string;
+  },
 ): Schema.Codec<Handle<Contract_>, string> =>
-  Schema.String.pipe(
+  Schema.String.annotate({ [CallbackContract]: contract }).pipe(
     Schema.decodeTo(
       Schema.declare(isHandleOf(contract), {
         identifier: `Callback.Handle<${contract.id}>`,
       }),
       {
         decode: SchemaGetter.transform((text: string) =>
-          fromText(contract, text),
+          fromText(contract, text, options?.reservedArgument),
         ),
         encode: SchemaGetter.transform(
           (ref: Handle<Contract_>) => ref.convexFunctionName,
@@ -301,4 +314,4 @@ export const toFuture = <Ref_ extends Ref.Any>(
   Ref.GetFunctionVisibility<Ref_>,
   EncodedArgs<Ref_>,
   EncodedReturns<Ref_>
-> => Ref.getFunctionReference(ref) as never;
+> => getFunctionReference(ref) as never;