@memoryengine/client 0.1.0

package/src/schemas/rpc.ts

@@ -0,0 +1,291 @@
+/**
+ * RPC Contract - maps method names to input/output types
+ *
+ * This is the key to type inference: define the contract once,
+ * and both server validation and client types are derived from it.
+ */
+import { z } from "zod";
+// Auth schemas
+import {
+  apiKeySchema,
+  createApiKeyResultSchema,
+  createApiKeySchema,
+  loginResultSchema,
+  loginSchema,
+  principalSchema,
+  revokeApiKeySchema,
+  successSchema,
+  whoamiSchema,
+} from "./auth";
+// Engram schemas
+import {
+  batchCreateEngramSchema,
+  batchCreateResultSchema,
+  createEngramSchema,
+  deleteEngramSchema,
+  deleteResultSchema,
+  engramSchema,
+  getEngramSchema,
+  mvEngramResultSchema,
+  mvEngramSchema,
+  searchEngramResultSchema,
+  searchEngramSchema,
+  updateEngramSchema,
+} from "./engram";
+
+// Principal schemas
+import {
+  addRoleMemberSchema,
+  checkTreeAccessSchema,
+  createPrincipalSchema,
+  deletePrincipalSchema,
+  getPrincipalSchema,
+  getTreeOwnerSchema,
+  grantTreeAccessSchema,
+  listRoleMembersSchema,
+  listRolesForPrincipalSchema,
+  listTreeGrantsSchema,
+  listTreeOwnersSchema,
+  principalDetailSchema,
+  principalListItemSchema,
+  principalRoleSchema,
+  removeRoleMemberSchema,
+  removeTreeOwnerSchema,
+  revokeTreeAccessSchema,
+  roleMemberSchema,
+  setPasswordSchema,
+  setTreeOwnerSchema,
+  treeGrantSchema,
+  treeOwnerSchema,
+} from "./principal";
+
+// ===== RPC Method Definition =====
+
+/**
+ * Define a method with its input schema and output type.
+ * The output type is specified as a generic since DB results
+ * aren't validated at runtime (trusted internal data).
+ *
+ * Uses z.input<> for input types to preserve optionality of fields
+ * with defaults (e.g., limit?: number with .default(100) stays optional
+ * for callers, but the server gets the default after parsing).
+ */
+function method<TInput extends z.ZodType, TOutput>(
+  input: TInput,
+  _output?: TOutput,
+) {
+  return {
+    input,
+    _types: {} as {
+      input: z.input<TInput>;
+      output: TOutput;
+    },
+  };
+}
+
+/** For methods with no input params */
+const emptySchema = z.object({});
+
+// ===== Auth Methods Contract =====
+
+export const authMethods = {
+  "auth.login": method(loginSchema, {} as z.infer<typeof loginResultSchema>),
+  "auth.whoami": method(emptySchema, {} as z.infer<typeof whoamiSchema>),
+  "auth.createApiKey": method(
+    createApiKeySchema,
+    {} as z.infer<typeof createApiKeyResultSchema>,
+  ),
+  "auth.listApiKeys": method(emptySchema, {} as z.infer<typeof apiKeySchema>[]),
+  "auth.revokeApiKey": method(
+    revokeApiKeySchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+} as const;
+
+// ===== Principal Methods Contract =====
+
+export const principalMethods = {
+  "principal.list": method(
+    emptySchema,
+    {} as z.infer<typeof principalListItemSchema>[],
+  ),
+  "principal.get": method(
+    getPrincipalSchema,
+    {} as z.infer<typeof principalDetailSchema>,
+  ),
+  "principal.create": method(
+    createPrincipalSchema,
+    {} as z.infer<typeof principalSchema>,
+  ),
+  "principal.delete": method(
+    deletePrincipalSchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+  "principal.setPassword": method(
+    setPasswordSchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+} as const;
+
+// ===== Grant Methods Contract =====
+
+export const grantMethods = {
+  "grant.create": method(
+    grantTreeAccessSchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+  "grant.revoke": method(
+    revokeTreeAccessSchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+  "grant.list": method(
+    listTreeGrantsSchema,
+    {} as z.infer<typeof treeGrantSchema>[],
+  ),
+  "grant.check": method(checkTreeAccessSchema, {} as { allowed: boolean }),
+} as const;
+
+// ===== Owner Methods Contract =====
+
+export const ownerMethods = {
+  "owner.set": method(setTreeOwnerSchema, {} as z.infer<typeof successSchema>),
+  "owner.remove": method(
+    removeTreeOwnerSchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+  "owner.get": method(
+    getTreeOwnerSchema,
+    {} as z.infer<typeof treeOwnerSchema> | null,
+  ),
+  "owner.list": method(
+    listTreeOwnersSchema,
+    {} as z.infer<typeof treeOwnerSchema>[],
+  ),
+} as const;
+
+// ===== Role Methods Contract =====
+
+export const roleMethods = {
+  "role.addMember": method(
+    addRoleMemberSchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+  "role.removeMember": method(
+    removeRoleMemberSchema,
+    {} as z.infer<typeof successSchema>,
+  ),
+  "role.listMembers": method(
+    listRoleMembersSchema,
+    {} as z.infer<typeof roleMemberSchema>[],
+  ),
+  "role.listForPrincipal": method(
+    listRolesForPrincipalSchema,
+    {} as z.infer<typeof principalRoleSchema>[],
+  ),
+} as const;
+
+// ===== Engram Methods Contract =====
+
+export const engramMethods = {
+  "engram.create": method(
+    createEngramSchema,
+    {} as z.infer<typeof engramSchema>,
+  ),
+  "engram.batchCreate": method(
+    batchCreateEngramSchema,
+    {} as z.infer<typeof batchCreateResultSchema>,
+  ),
+  "engram.get": method(getEngramSchema, {} as z.infer<typeof engramSchema>),
+  "engram.update": method(
+    updateEngramSchema,
+    {} as z.infer<typeof engramSchema>,
+  ),
+  "engram.delete": method(
+    deleteEngramSchema,
+    {} as z.infer<typeof deleteResultSchema>,
+  ),
+  "engram.search": method(
+    searchEngramSchema,
+    {} as z.infer<typeof searchEngramResultSchema>,
+  ),
+  "engram.mv": method(
+    mvEngramSchema,
+    {} as z.infer<typeof mvEngramResultSchema>,
+  ),
+} as const;
+
+// ===== Combined RPC Contract =====
+
+/** All registered RPC methods */
+export const rpcMethods = {
+  ...authMethods,
+  ...principalMethods,
+  ...grantMethods,
+  ...ownerMethods,
+  ...roleMethods,
+  ...engramMethods,
+} as const;
+
+/** Union of all method names */
+export type RpcMethodName = keyof typeof rpcMethods;
+
+/** Extract input type for a method */
+export type RpcInput<M extends RpcMethodName> =
+  (typeof rpcMethods)[M]["_types"]["input"];
+
+/** Extract output type for a method */
+export type RpcOutput<M extends RpcMethodName> =
+  (typeof rpcMethods)[M]["_types"]["output"];
+
+/** Get the input schema for runtime validation */
+export function getInputSchema<M extends RpcMethodName>(method: M) {
+  return rpcMethods[method].input;
+}
+
+// ===== Output Schema Map =====
+
+const checkAccessOutputSchema = z.object({ allowed: z.boolean() });
+
+/** Runtime output schemas for response validation */
+const outputSchemas: Record<string, z.ZodType> = {
+  // Auth
+  "auth.login": loginResultSchema,
+  "auth.whoami": whoamiSchema,
+  "auth.createApiKey": createApiKeyResultSchema,
+  "auth.listApiKeys": z.array(apiKeySchema),
+  "auth.revokeApiKey": successSchema,
+  // Principal
+  "principal.list": z.array(principalListItemSchema),
+  "principal.get": principalDetailSchema,
+  "principal.create": principalSchema,
+  "principal.delete": successSchema,
+  "principal.setPassword": successSchema,
+  // Grant
+  "grant.create": successSchema,
+  "grant.revoke": successSchema,
+  "grant.list": z.array(treeGrantSchema),
+  "grant.check": checkAccessOutputSchema,
+  // Owner
+  "owner.set": successSchema,
+  "owner.remove": successSchema,
+  "owner.get": treeOwnerSchema.nullable(),
+  "owner.list": z.array(treeOwnerSchema),
+  // Role
+  "role.addMember": successSchema,
+  "role.removeMember": successSchema,
+  "role.listMembers": z.array(roleMemberSchema),
+  "role.listForPrincipal": z.array(principalRoleSchema),
+  // Engram
+  "engram.create": engramSchema,
+  "engram.batchCreate": batchCreateResultSchema,
+  "engram.get": engramSchema,
+  "engram.update": engramSchema,
+  "engram.delete": deleteResultSchema,
+  "engram.search": searchEngramResultSchema,
+  "engram.mv": mvEngramResultSchema,
+};
+
+/** Get the output schema for runtime response validation */
+export function getOutputSchema(method: string): z.ZodType | undefined {
+  return outputSchemas[method];
+}