jazz-tools 0.18.25 → 0.18.27

package/src/tools/implementation/zodSchema/runtimeConverters/coValueSchemaTransformation.ts

@@ -12,12 +12,14 @@ import {
   CoValueClass,
   FileStream,
   FileStreamSchema,
+  CoVectorSchema,
   PlainTextSchema,
   SchemaUnion,
   enrichAccountSchema,
   enrichCoMapSchema,
   isCoValueClass,
   Group,
+  CoVector,
 } from "../../../internal.js";
 import { coField } from "../../schema.js";
 
@@ -123,6 +125,17 @@ export function hydrateCoreCoValueSchema<S extends AnyCoreCoValueSchema>(
   } else if (schema.builtin === "FileStream") {
     const coValueClass = FileStream;
     return new FileStreamSchema(coValueClass) as CoValueSchemaFromCoreSchema<S>;
+  } else if (schema.builtin === "CoVector") {
+    const dimensions = schema.dimensions;
+
+    const coValueClass = class CoVectorWithDimensions extends CoVector {
+      protected static requiredDimensionsCount = dimensions;
+    };
+
+    return new CoVectorSchema(
+      dimensions,
+      coValueClass,
+    ) as CoValueSchemaFromCoreSchema<S>;
   } else if (schema.builtin === "CoPlainText") {
     const coValueClass = CoPlainText;
     return new PlainTextSchema(coValueClass) as CoValueSchemaFromCoreSchema<S>;

package/src/tools/implementation/zodSchema/schemaTypes/CoVectorSchema.ts

@@ -0,0 +1,105 @@
+import {
+  Account,
+  AnonymousJazzAgent,
+  CoVector,
+  Group,
+  InstanceOrPrimitiveOfSchema,
+  InstanceOrPrimitiveOfSchemaCoValuesNullable,
+  coOptionalDefiner,
+} from "../../../internal.js";
+import { CoOptionalSchema } from "./CoOptionalSchema.js";
+import { CoreCoValueSchema } from "./CoValueSchema.js";
+
+export interface CoreCoVectorSchema extends CoreCoValueSchema {
+  builtin: "CoVector";
+  dimensions: number;
+}
+
+export function createCoreCoVectorSchema(
+  dimensions: number,
+): CoreCoVectorSchema {
+  return {
+    collaborative: true as const,
+    builtin: "CoVector" as const,
+    dimensions,
+  };
+}
+
+export class CoVectorSchema implements CoreCoVectorSchema {
+  readonly collaborative = true as const;
+  readonly builtin = "CoVector" as const;
+
+  constructor(
+    public dimensions: number,
+    private coValueClass: typeof CoVector,
+  ) {}
+
+  /**
+   * Create a `CoVector` from a given vector.
+   */
+  create(
+    vector: number[] | Float32Array,
+    options?: { owner: Group } | Group,
+  ): CoVectorInstance;
+  /**
+   * Create a `CoVector` from a given vector.
+   *
+   * @deprecated Creating CoValues with an Account as owner is deprecated. Use a Group instead.
+   */
+  create(
+    vector: number[] | Float32Array,
+    options?: { owner: Account | Group } | Account | Group,
+  ): CoVectorInstance;
+  create(
+    vector: number[] | Float32Array,
+    options?: { owner: Account | Group } | Account | Group,
+  ): CoVectorInstance {
+    return this.coValueClass.create(vector, options);
+  }
+
+  /**
+   * Load a `CoVector` with a given ID.
+   */
+  load(
+    id: string,
+    options?: { loadAs: Account | AnonymousJazzAgent },
+  ): Promise<CoVectorInstanceNullable> {
+    return this.coValueClass.load(id, options);
+  }
+
+  /**
+   * Subscribe to a `CoVector`, when you have an ID but don't have a `CoVector` instance yet
+   */
+  subscribe(
+    id: string,
+    options: { loadAs: Account | AnonymousJazzAgent },
+    listener: (
+      value: CoVectorInstanceNullable,
+      unsubscribe: () => void,
+    ) => void,
+  ): () => void;
+  subscribe(
+    id: string,
+    listener: (
+      value: CoVectorInstanceNullable,
+      unsubscribe: () => void,
+    ) => void,
+  ): () => void;
+  subscribe(...args: [any, ...any[]]) {
+    // @ts-expect-error
+    return this.coValueClass.subscribe(...args);
+  }
+
+  getCoValueClass(): typeof CoVector {
+    return this.coValueClass;
+  }
+
+  optional(): CoOptionalSchema<this> {
+    return coOptionalDefiner(this);
+  }
+}
+
+export type CoVectorInstance = InstanceOrPrimitiveOfSchema<CoVectorSchema>;
+
+export type CoVectorInstanceNullable =
+  InstanceOrPrimitiveOfSchemaCoValuesNullable<CoVectorSchema>;

package/src/tools/implementation/zodSchema/typeConverters/InstanceOfSchema.ts

@@ -7,9 +7,11 @@ import {
   CoMap,
   CoPlainText,
   CoRichText,
+  CoVector,
   CoValueClass,
   CoreAccountSchema,
   CoreCoRecordSchema,
+  CoreCoVectorSchema,
   FileStream,
   Group,
 } from "../../../internal.js";
@@ -63,11 +65,13 @@ export type InstanceOfSchema<S extends CoValueClass | AnyZodOrCoValueSchema> =
                     ? CoRichText
                     : S extends CoreFileStreamSchema
                       ? FileStream
-                      : S extends CoreCoOptionalSchema<infer T>
-                        ? InstanceOrPrimitiveOfSchema<T> | undefined
-                        : S extends CoDiscriminatedUnionSchema<infer Members>
-                          ? InstanceOrPrimitiveOfSchema<Members[number]>
-                          : never
+                      : S extends CoreCoVectorSchema
+                        ? Readonly<CoVector>
+                        : S extends CoreCoOptionalSchema<infer T>
+                          ? InstanceOrPrimitiveOfSchema<T> | undefined
+                          : S extends CoDiscriminatedUnionSchema<infer Members>
+                            ? InstanceOrPrimitiveOfSchema<Members[number]>
+                            : never
     : S extends CoValueClass
       ? InstanceType<S>
       : never;

package/src/tools/implementation/zodSchema/typeConverters/InstanceOfSchemaCoValuesNullable.ts

@@ -13,6 +13,8 @@ import {
   CoreCoListSchema,
   CoreCoMapSchema,
   CoreCoRecordSchema,
+  CoreCoVectorSchema,
+  CoVector,
   FileStream,
   Group,
 } from "../../../internal.js";
@@ -70,15 +72,19 @@ export type InstanceOfSchemaCoValuesNullable<
                   ? CoRichText | null
                   : S extends CoreFileStreamSchema
                     ? FileStream | null
-                    : S extends CoreCoOptionalSchema<infer Inner>
-                      ?
-                          | InstanceOrPrimitiveOfSchemaCoValuesNullable<Inner>
-                          | undefined
-                      : S extends CoreCoDiscriminatedUnionSchema<infer Members>
-                        ? InstanceOrPrimitiveOfSchemaCoValuesNullable<
-                            Members[number]
-                          >
-                        : never
+                    : S extends CoreCoVectorSchema
+                      ? Readonly<CoVector> | null
+                      : S extends CoreCoOptionalSchema<infer Inner>
+                        ?
+                            | InstanceOrPrimitiveOfSchemaCoValuesNullable<Inner>
+                            | undefined
+                        : S extends CoreCoDiscriminatedUnionSchema<
+                              infer Members
+                            >
+                          ? InstanceOrPrimitiveOfSchemaCoValuesNullable<
+                              Members[number]
+                            >
+                          : never
   : S extends CoValueClass
     ? InstanceType<S> | null
     : never;

package/src/tools/implementation/zodSchema/zodCo.ts

@@ -9,6 +9,7 @@ import {
   type CoRecordSchema,
   type DefaultProfileShape,
   type FileStreamSchema,
+  type CoVectorSchema,
   ImageDefinition,
   type PlainTextSchema,
   type Simplify,
@@ -18,6 +19,7 @@ import {
   createCoreCoMapSchema,
   createCoreCoPlainTextSchema,
   createCoreFileStreamSchema,
+  createCoreCoVectorSchema,
   hydrateCoreCoValueSchema,
   isAnyCoValueSchema,
   isCoValueClass,
@@ -193,6 +195,19 @@ export const coFileStreamDefiner = (): FileStreamSchema => {
   return hydrateCoreCoValueSchema(coreSchema);
 };
 
+export const coVectorDefiner = (dimensions: number): CoVectorSchema => {
+  const isPositiveInteger = Number.isInteger(dimensions) && dimensions > 0;
+
+  if (!isPositiveInteger) {
+    throw new Error(
+      "co.vector() expects the vector dimensions count to be a positive integer",
+    );
+  }
+
+  const coreSchema = createCoreCoVectorSchema(dimensions);
+  return hydrateCoreCoValueSchema(coreSchema);
+};
+
 export const coPlainTextDefiner = (): PlainTextSchema => {
   const coreSchema = createCoreCoPlainTextSchema();
   return hydrateCoreCoValueSchema(coreSchema);

package/src/tools/implementation/zodSchema/zodSchema.ts

@@ -33,6 +33,10 @@ import {
   CoreFileStreamSchema,
   FileStreamSchema,
 } from "./schemaTypes/FileStreamSchema.js";
+import {
+  CoreCoVectorSchema,
+  CoVectorSchema,
+} from "./schemaTypes/CoVectorSchema.js";
 import {
   CorePlainTextSchema,
   PlainTextSchema,
@@ -75,11 +79,15 @@ export type CoValueSchemaFromCoreSchema<S extends CoreCoValueSchema> =
                   ? RichTextSchema
                   : S extends CoreFileStreamSchema
                     ? FileStreamSchema
-                    : S extends CoreCoOptionalSchema<infer Inner>
-                      ? CoOptionalSchema<Inner>
-                      : S extends CoreCoDiscriminatedUnionSchema<infer Members>
-                        ? CoDiscriminatedUnionSchema<Members>
-                        : never;
+                    : S extends CoreCoVectorSchema
+                      ? CoVectorSchema
+                      : S extends CoreCoOptionalSchema<infer Inner>
+                        ? CoOptionalSchema<Inner>
+                        : S extends CoreCoDiscriminatedUnionSchema<
+                              infer Members
+                            >
+                          ? CoDiscriminatedUnionSchema<Members>
+                          : never;
 
 export type CoValueClassFromAnySchema<S extends CoValueClassOrSchema> =
   S extends CoValueClass<any>
@@ -104,7 +112,8 @@ export type AnyCoreCoValueSchema =
   | CoreCoOptionalSchema
   | CorePlainTextSchema
   | CoreRichTextSchema
-  | CoreFileStreamSchema;
+  | CoreFileStreamSchema
+  | CoreCoVectorSchema;
 
 export type AnyZodSchema = z.core.$ZodType;
 

package/src/tools/internal.ts

@@ -16,6 +16,7 @@ export * from "./coValues/inbox.js";
 export * from "./coValues/coPlainText.js";
 export * from "./coValues/coRichText.js";
 export * from "./coValues/schemaUnion.js";
+export * from "./coValues/coVector.js";
 
 export type * from "./subscribe/types.js";
 
@@ -43,6 +44,7 @@ export * from "./implementation/zodSchema/schemaTypes/CoListSchema.js";
 export * from "./implementation/zodSchema/schemaTypes/CoFeedSchema.js";
 export * from "./implementation/zodSchema/schemaTypes/AccountSchema.js";
 export * from "./implementation/zodSchema/schemaTypes/FileStreamSchema.js";
+export * from "./implementation/zodSchema/schemaTypes/CoVectorSchema.js";
 export * from "./implementation/zodSchema/schemaTypes/PlainTextSchema.js";
 export * from "./implementation/zodSchema/typeConverters/InstanceOrPrimitiveOfSchema.js";
 export * from "./implementation/zodSchema/typeConverters/InstanceOrPrimitiveOfSchemaCoValuesNullable.js";

package/src/tools/tests/authenticate-request.test.ts

@@ -0,0 +1,194 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { authenticateRequest, generateAuthToken } from "../coValues/request.js";
+import { createJazzTestAccount } from "../testing.js";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("authenticateRequest", () => {
+  it("should correctly authenticate a request", async () => {
+    const me = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${token}`,
+        },
+      }),
+    );
+
+    expect(error).toBeUndefined();
+    expect(account?.$jazz.id).toBe(me.$jazz.id);
+  });
+
+  it("should not return an account if no token is provided", async () => {
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {}),
+    );
+
+    expect(error).toBeUndefined();
+    expect(account).toBeUndefined();
+  });
+
+  it("should return an error if the token is invalid", async () => {
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz invalid~invalid~invalid`,
+        },
+      }),
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Invalid token",
+        details: expect.anything(),
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should return an error if the token is malformed", async () => {
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz malformed`,
+        },
+      }),
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Invalid token",
+        details: expect.anything(),
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should be resilient to tampering", async () => {
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+    const tokenParts = token.split("~");
+    tokenParts[2] = "999999999999999";
+    const tamperedToken = tokenParts.join("~");
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${tamperedToken}`,
+        },
+      }),
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Invalid signature",
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should return an error if the token is expired", async () => {
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${token}`,
+        },
+      }),
+      {
+        expiration: -1000,
+      },
+    );
+
+    expect(error).toMatchObject(
+      expect.objectContaining({
+        message: "Token expired",
+      }),
+    );
+    expect(account).toBeUndefined();
+  });
+
+  it("should treat the request as unauthenticated if the token is not in the default format, even if present.", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `${token}`,
+        },
+      }),
+    );
+
+    expect(console.warn).toHaveBeenCalled();
+    expect(account).toBeUndefined();
+    expect(error).toBeUndefined();
+  });
+
+  it("should correctly validate a request when the token is in a non standard location", async () => {
+    const me = await createJazzTestAccount({
+      isCurrentActiveAccount: true,
+    });
+
+    const token = generateAuthToken();
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          ["x-jazz-auth-token"]: `${token}`,
+        },
+      }),
+      {
+        getToken: (request) => request.headers.get("x-jazz-auth-token"),
+      },
+    );
+
+    expect(error).toBeUndefined();
+    expect(account?.$jazz.id).toBe(me.$jazz.id);
+  });
+
+  it("should correctly validate a request when the token is generated from a non active account", async () => {
+    const notAnActiveAccount = await createJazzTestAccount({
+      isCurrentActiveAccount: false,
+    });
+
+    const token = generateAuthToken(notAnActiveAccount);
+
+    const { account, error } = await authenticateRequest(
+      new Request("https://api.example.com/api/user", {
+        headers: {
+          Authorization: `Jazz ${token}`,
+        },
+      }),
+      {
+        loadAs: notAnActiveAccount,
+      },
+    );
+
+    expect(error).toBeUndefined();
+    expect(account?.$jazz.id).toBe(notAnActiveAccount.$jazz.id);
+  });
+});

package/src/tools/tests/coVector.test-d.ts

@@ -0,0 +1,40 @@
+import { describe, expectTypeOf, test } from "vitest";
+import { Group, co } from "../exports.js";
+import { CoVectorSchema } from "../internal.js";
+
+describe("CoVector types", () => {
+  test("co.vector() • defines a correct CoVectorSchema", () => {
+    type ExpectedType = CoVectorSchema;
+
+    function matches(value: ExpectedType) {
+      return value;
+    }
+
+    matches(co.vector(384));
+  });
+
+  test("co.vector().create() • creates a CoVector with Float32Array-like typing", () => {
+    const embedding = co.vector(3).create([1, 2, 3]);
+
+    type ExpectedType = Readonly<Float32Array>;
+
+    function matches(value: ExpectedType) {
+      return value;
+    }
+
+    matches(embedding);
+  });
+
+  test("CoVector instance • has the owner property", () => {
+    const embedding = co.vector(3).create([1, 2, 3]);
+
+    expectTypeOf(embedding.$jazz.owner).toEqualTypeOf<Group>();
+  });
+
+  test("setting a value via index access • is a type error", () => {
+    const embedding = co.vector(3).create([1, 2, 3]);
+
+    // @ts-expect-error: assignment to index should be disallowed
+    embedding[0] = 6;
+  });
+});