@gaganref/confect-core 10.3.1-fork.7 → 10.3.1-fork.71

package/src/Auth.ts

@@ -1,9 +1,11 @@
 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 type { TypeError } from "./Types.js";
 
 const TypeId = "~@confect/core/Auth";
+const CloudUrlTypeId = "~@confect/core/Auth/CloudUrl";
 const SiteUrlTypeId = "~@confect/core/Auth/SiteUrl";
 
 /**
@@ -15,19 +17,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;

package/src/Callback.ts

@@ -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;

package/src/Component.ts

@@ -215,7 +215,7 @@ export type Bound<
 /**
  * Build a publishable contract containing only exported functions and codecs.
  */
-export const make = <
+export const contract = <
   Spec_ extends Spec.AnyWithProps,
   const Scope extends IdScope.IdScope,
   const Tables extends string,
@@ -275,14 +275,14 @@ export const bind = <
   MountScope<Parent, Extract<MountName<Native>, string | undefined>>,
   Tables
 > => {
-  const contract = component[TypeId];
+  const published = component[TypeId];
   const address = getFunctionAddress(native);
   const installedReference = Result.getOrThrow(
     Result.fromNullishOr(
       address.reference,
       () =>
         new UninstalledComponentReferenceError({
-          definitionScope: contract.scope,
+          definitionScope: published.scope,
         }),
     ),
   );
@@ -293,7 +293,7 @@ export const bind = <
     installedReference,
   );
   const rebase = (schema: Schema.ConstraintCodec<any, any, never, never>) =>
-    GenericId.rebase(schema, contract.scope, scope);
+    GenericId.rebase(schema, published.scope, scope);
   const rebaseMiddleware = memoize(
     (middleware: MiddlewareSpec.AnyMiddlewareSpec) => {
       if (!("error" in middleware)) return middleware;
@@ -358,6 +358,8 @@ export const bind = <
                 spec: rebaseMiddleware(attachment.spec),
               })),
               nativeRef,
+              ref.functionType,
+              ref.reservedArgument,
             );
           }),
           Match.exhaustive,
@@ -366,9 +368,9 @@ export const bind = <
         return visit(child, reference);
       }
     });
-  const refs = visit(contract.refs, native);
+  const refs = visit(published.refs, native);
   Object.defineProperty(refs, BoundTypeId, {
-    value: { from: contract.scope, scope, tables: contract.tables },
+    value: { from: published.scope, scope, tables: published.tables },
   });
   return refs as Bound<
     Spec_,