@zoralabs/coins-sdk 0.2.4 → 0.2.6

package/src/uploader/metadata.ts

@@ -0,0 +1,214 @@
+import {
+  CreateMetadataParameters,
+  Uploader,
+  UploadResult,
+  ValidMetadataURI,
+} from "./types";
+
+type Metadata = {
+  name: string;
+  symbol: string;
+  description: string;
+  image: string;
+  properties?: Record<string, string>;
+  animation_url?: string;
+  content?: {
+    uri: string;
+    mime: string | undefined;
+  };
+};
+
+export function validateImageMimeType(mimeType: string) {
+  if (
+    ![
+      "image/png",
+      "image/jpeg",
+      "image/jpg",
+      "image/gif",
+      "image/svg+xml",
+    ].includes(mimeType)
+  ) {
+    throw new Error("Image must be a PNG, JPEG, JPG, GIF or SVG");
+  }
+}
+
+export function getURLFromUploadResult(uploadResult: UploadResult) {
+  return new URL(uploadResult.url);
+}
+
+export class CoinMetadataBuilder {
+  private name: string | undefined;
+  private description: string | undefined;
+  private symbol: string | undefined;
+  private imageFile: File | undefined;
+  private imageURL: URL | undefined;
+  private mediaFile: File | undefined;
+  private mediaURL: URL | undefined;
+  private mediaMimeType: string | undefined;
+  private properties: Record<string, string> | undefined;
+
+  withName(name: string) {
+    this.name = name;
+    if (typeof name !== "string") {
+      throw new Error("Name must be a string");
+    }
+
+    return this;
+  }
+
+  withSymbol(symbol: string) {
+    this.symbol = symbol;
+    if (typeof symbol !== "string") {
+      throw new Error("Symbol must be a string");
+    }
+
+    return this;
+  }
+
+  withDescription(description: string) {
+    this.description = description;
+    if (typeof description !== "string") {
+      throw new Error("Description must be a string");
+    }
+
+    return this;
+  }
+
+  withImage(image: File) {
+    if (this.imageURL) {
+      throw new Error("Image URL already set");
+    }
+    if (!(image instanceof File)) {
+      throw new Error("Image must be a File");
+    }
+    validateImageMimeType(image.type);
+    this.imageFile = image;
+
+    return this;
+  }
+
+  withImageURI(imageURI: string) {
+    if (this.imageFile) {
+      throw new Error("Image file already set");
+    }
+    if (typeof imageURI !== "string") {
+      throw new Error("Image URI must be a string");
+    }
+    const url = new URL(imageURI);
+    this.imageURL = url;
+
+    return this;
+  }
+
+  withProperties(properties: Record<string, string>) {
+    for (const [key, value] of Object.entries(properties)) {
+      if (typeof key !== "string") {
+        throw new Error("Property key must be a string");
+      }
+      if (typeof value !== "string") {
+        throw new Error("Property value must be a string");
+      }
+    }
+    if (!this.properties) {
+      this.properties = {};
+    }
+    this.properties = { ...this.properties, ...properties };
+
+    return this;
+  }
+
+  withMedia(media: File) {
+    if (this.mediaURL) {
+      throw new Error("Media URL already set");
+    }
+    if (!(media instanceof File)) {
+      throw new Error("Media must be a File");
+    }
+    this.mediaMimeType = media.type;
+    this.mediaFile = media;
+
+    return this;
+  }
+
+  withMediaURI(mediaURI: string, mediaMimeType: string | undefined) {
+    if (this.mediaFile) {
+      throw new Error("Media file already set");
+    }
+    if (typeof mediaURI !== "string") {
+      throw new Error("Media URI must be a string");
+    }
+    const url = new URL(mediaURI);
+    this.mediaURL = url;
+    this.mediaMimeType = mediaMimeType;
+
+    return this;
+  }
+
+  validate() {
+    if (!this.name) {
+      throw new Error("Name is required");
+    }
+    if (!this.symbol) {
+      throw new Error("Symbol is required");
+    }
+    if (!this.imageFile && !this.imageURL) {
+      throw new Error("Image is required");
+    }
+
+    return this;
+  }
+
+  generateMetadata(): Metadata {
+    return {
+      name: this.name!,
+      symbol: this.symbol!,
+      description: this.description!,
+      image: this.imageURL!.toString(),
+      animation_url: this.mediaURL?.toString(),
+      content: this.mediaURL
+        ? {
+            uri: this.mediaURL?.toString(),
+            mime: this.mediaMimeType,
+          }
+        : undefined,
+      properties: this.properties,
+    };
+  }
+
+  async upload(uploader: Uploader): Promise<{
+    url: ValidMetadataURI;
+    createMetadataParameters: CreateMetadataParameters;
+    metadata: Metadata;
+  }> {
+    this.validate();
+
+    if (this.imageFile) {
+      const uploadResult = await uploader.upload(this.imageFile);
+      this.imageURL = getURLFromUploadResult(uploadResult);
+    }
+    if (this.mediaFile) {
+      const uploadResult = await uploader.upload(this.mediaFile);
+      this.mediaURL = getURLFromUploadResult(uploadResult);
+    }
+    const metadata = this.generateMetadata();
+    const uploadResult = await uploader.upload(
+      new File([JSON.stringify(metadata)], "metadata.json", {
+        type: "application/json",
+      }),
+    );
+
+    return {
+      url: getURLFromUploadResult(uploadResult).toString() as ValidMetadataURI,
+      createMetadataParameters: {
+        name: this.name!,
+        symbol: this.symbol!,
+        uri: uploadResult.url as `ipfs://${string}`,
+      },
+      metadata,
+    };
+  }
+}
+
+export function createMetadataBuilder() {
+  return new CoinMetadataBuilder();
+}

package/src/uploader/providers/zora.ts

@@ -0,0 +1,86 @@
+import { Address } from "viem";
+import { Uploader, UploadResult } from "../types";
+import { getApiKey } from "../../api/api-key";
+import { setCreateUploadJwt } from "../../api/internal";
+
+/**
+ * Zora IPFS uploader implementation
+ */
+export class ZoraUploader implements Uploader {
+  constructor(creatorAddress: Address) {
+    this.creatorAddress = creatorAddress;
+    if (!getApiKey()) {
+      throw new Error("API key is required for metadata interactions");
+    }
+  }
+
+  private creatorAddress: Address;
+  private jwtApiKey: string | undefined;
+  private jwtApiKeyExpiresAt: number | undefined;
+
+  async getJWTApiKey() {
+    if (
+      this.jwtApiKey &&
+      this.jwtApiKeyExpiresAt &&
+      this.jwtApiKeyExpiresAt > Date.now()
+    ) {
+      return this.jwtApiKey;
+    }
+    // Expires in 1 hour
+    this.jwtApiKeyExpiresAt = Date.now() + 1000 * 60 * 60;
+
+    const response = await setCreateUploadJwt({
+      creatorAddress: this.creatorAddress,
+    });
+    this.jwtApiKey = response.data?.createUploadJwtFromApiKey;
+    if (!this.jwtApiKey) {
+      throw new Error("Failed to create upload JWT");
+    }
+
+    return this.jwtApiKey;
+  }
+
+  async upload(file: File): Promise<UploadResult> {
+    const jwtApiKey = await this.getJWTApiKey();
+    const formData = new FormData();
+    formData.append("file", file, file.name);
+
+    const response = await fetch(
+      "https://ipfs-uploader.zora.co/api/v0/add?cid-version=1",
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${jwtApiKey}`,
+          Accept: "*/*",
+        },
+        body: formData,
+      },
+    );
+
+    if (!response.ok) {
+      console.error(await response.text());
+      throw new Error(`Failed to upload file: ${response.statusText}`);
+    }
+
+    const data = (await response.json()) as {
+      cid: string;
+      size: number | undefined;
+      mimeType: string | undefined;
+    };
+
+    return {
+      url: `ipfs://${data.cid}`,
+      size: data.size,
+      mimeType: data.mimeType,
+    };
+  }
+}
+
+/**
+ * Create a new Zora IPFS uploader
+ */
+export function createZoraUploaderForCreator(
+  creatorAddress: Address,
+): Uploader {
+  return new ZoraUploader(creatorAddress);
+}

package/src/uploader/tests/metadata.test.ts

@@ -0,0 +1,331 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import {
+  CoinMetadataBuilder,
+  validateImageMimeType,
+  getURLFromUploadResult,
+} from "../metadata";
+import { Uploader, UploadResult } from "../types";
+
+enum UploadResultType {
+  Image = "image",
+  Media = "media",
+  Metadata = "metadata",
+}
+
+// Create a mock implementation of the Uploader interface
+const createMockUploader = (resultList: UploadResultType[]) => {
+  // Pre-defined results to return from the upload method
+  const mockImageResult: UploadResult = {
+    url: "ipfs://image-cid",
+    size: 100,
+    mimeType: "image/png",
+  };
+
+  const mockMediaResult: UploadResult = {
+    url: "ipfs://media-cid",
+    size: 200,
+    mimeType: "video/mp4",
+  };
+
+  const mockMetadataResult: UploadResult = {
+    url: "ipfs://metadata-cid",
+    size: 300,
+    mimeType: "application/json",
+  };
+
+  const uploadedFiles: File[] = [];
+  let callCount = 0;
+
+  const mockUploader: Uploader = {
+    upload: vi.fn(async (file: File): Promise<UploadResult> => {
+      uploadedFiles.push(file);
+      callCount++;
+
+      switch (resultList[callCount - 1]) {
+        case UploadResultType.Image:
+          return mockImageResult;
+        case UploadResultType.Media:
+          return mockMediaResult;
+        case UploadResultType.Metadata:
+          return mockMetadataResult;
+        default:
+          throw new Error(`Invalid result type: ${resultList[callCount - 1]}`);
+      }
+    }),
+  };
+
+  return {
+    uploader: mockUploader,
+    uploadedFiles,
+    mockImageResult,
+    mockMediaResult,
+    mockMetadataResult,
+    reset: () => {
+      callCount = 0;
+      uploadedFiles.length = 0;
+      vi.clearAllMocks();
+    },
+  };
+};
+
+describe("validateImageMimeType", () => {
+  it("should not throw for valid image types", () => {
+    const validTypes = [
+      "image/png",
+      "image/jpeg",
+      "image/jpg",
+      "image/gif",
+      "image/svg+xml",
+    ];
+
+    validTypes.forEach((type) => {
+      expect(() => validateImageMimeType(type)).not.toThrow();
+    });
+  });
+
+  it("should throw for invalid image types", () => {
+    const invalidTypes = ["image/webp", "application/pdf", "text/plain"];
+
+    invalidTypes.forEach((type) => {
+      expect(() => validateImageMimeType(type)).toThrow(
+        "Image must be a PNG, JPEG, JPG, GIF or SVG",
+      );
+    });
+  });
+});
+
+describe("getURLFromUploadResult", () => {
+  it("should convert an upload result URL to a URL object", () => {
+    const result: UploadResult = {
+      url: "ipfs://bafybeiguslukdujd22p7ix53rcszgbg4ine464g33zk2st3lnjpx4uvmri",
+      size: 100,
+      mimeType: "image/png",
+    };
+
+    const url = getURLFromUploadResult(result);
+    expect(url).toBeInstanceOf(URL);
+    expect(url.toString()).toBe(
+      "ipfs://bafybeiguslukdujd22p7ix53rcszgbg4ine464g33zk2st3lnjpx4uvmri",
+    );
+  });
+
+  it("should throw for invalid URLs", () => {
+    const result: UploadResult = {
+      url: "invalid-url",
+      size: 100,
+      mimeType: "image/png",
+    };
+
+    expect(() => getURLFromUploadResult(result)).toThrow();
+  });
+});
+
+describe("CoinMetadataBuilder", () => {
+  let mockUploaderData: ReturnType<typeof createMockUploader>;
+  let builder: CoinMetadataBuilder;
+
+  beforeEach(() => {
+    mockUploaderData = createMockUploader([
+      UploadResultType.Image,
+      UploadResultType.Media,
+      UploadResultType.Metadata,
+    ]);
+    builder = new CoinMetadataBuilder();
+  });
+
+  describe("builder methods", () => {
+    it("should set name and return self", () => {
+      const result = builder.withName("Test Coin");
+      expect(result).toBe(builder);
+    });
+
+    it("should set symbol and return self", () => {
+      const result = builder.withSymbol("TEST");
+      expect(result).toBe(builder);
+    });
+
+    it("should set description and return self", () => {
+      const result = builder.withDescription("Test Description");
+      expect(result).toBe(builder);
+    });
+
+    it("should set image file and return self", () => {
+      const imageFile = new File(["test"], "test.png", { type: "image/png" });
+      const result = builder.withImage(imageFile);
+      expect(result).toBe(builder);
+    });
+
+    it("should throw if image URL is already set when setting image file", () => {
+      builder.withImageURI("ipfs://test");
+      const imageFile = new File(["test"], "test.png", { type: "image/png" });
+      expect(() => builder.withImage(imageFile)).toThrow(
+        "Image URL already set",
+      );
+    });
+
+    it("should throw if image file is already set when setting image URI", () => {
+      const imageFile = new File(["test"], "test.png", { type: "image/png" });
+      builder.withImage(imageFile);
+      expect(() => builder.withImageURI("ipfs://test")).toThrow(
+        "Image file already set",
+      );
+    });
+
+    it("should set media file and return self", () => {
+      const mediaFile = new File(["test"], "test.mp4", { type: "video/mp4" });
+      const result = builder.withMedia(mediaFile);
+      expect(result).toBe(builder);
+    });
+
+    it("should throw if media URL is already set when setting media file", () => {
+      builder.withMediaURI("ipfs://test", "video/mp4");
+      const mediaFile = new File(["test"], "test.mp4", { type: "video/mp4" });
+      expect(() => builder.withMedia(mediaFile)).toThrow(
+        "Media URL already set",
+      );
+    });
+
+    it("should throw if media file is already set when setting media URI", () => {
+      const mediaFile = new File(["test"], "test.mp4", { type: "video/mp4" });
+      builder.withMedia(mediaFile);
+      expect(() => builder.withMediaURI("ipfs://test", "video/mp4")).toThrow(
+        "Media file already set",
+      );
+    });
+
+    it("should set properties and return self", () => {
+      const properties = { key1: "value1", key2: "value2" };
+      const result = builder.withProperties(properties);
+      expect(result).toBe(builder);
+    });
+
+    it("should throw if property value is not a string", () => {
+      const properties = { key1: "value1", key2: 123 as any };
+      expect(() => builder.withProperties(properties)).toThrow(
+        "Property value must be a string",
+      );
+    });
+  });
+
+  describe("validate", () => {
+    it("should throw if name is not set", () => {
+      builder
+        .withSymbol("TEST")
+        .withImage(new File(["test"], "test.png", { type: "image/png" }));
+      expect(() => builder.validate()).toThrow("Name is required");
+    });
+
+    it("should throw if symbol is not set", () => {
+      builder
+        .withName("Test Coin")
+        .withImage(new File(["test"], "test.png", { type: "image/png" }));
+      expect(() => builder.validate()).toThrow("Symbol is required");
+    });
+
+    it("should throw if image is not set", () => {
+      builder.withName("Test Coin").withSymbol("TEST");
+      expect(() => builder.validate()).toThrow("Image is required");
+    });
+
+    it("should not throw if all required fields are set", () => {
+      builder
+        .withName("Test Coin")
+        .withSymbol("TEST")
+        .withImage(new File(["test"], "test.png", { type: "image/png" }));
+
+      expect(() => builder.validate()).not.toThrow();
+    });
+  });
+
+  describe("generateMetadata", () => {
+    it("should generate correct metadata", () => {
+      builder
+        .withName("Test Coin")
+        .withSymbol("TEST")
+        .withDescription("Test Description")
+        .withImageURI("ipfs://image-cid")
+        .withMediaURI("ipfs://media-cid", "video/mp4")
+        .withProperties({ key1: "value1", key2: "value2" });
+
+      const metadata = builder.generateMetadata();
+
+      expect(metadata).toEqual({
+        name: "Test Coin",
+        symbol: "TEST",
+        description: "Test Description",
+        image: "ipfs://image-cid",
+        animation_url: "ipfs://media-cid",
+        content: {
+          uri: "ipfs://media-cid",
+          mime: "video/mp4",
+        },
+        properties: { key1: "value1", key2: "value2" },
+      });
+    });
+  });
+
+  describe("upload", () => {
+    it("should upload image, media and metadata", async () => {
+      const imageFile = new File(["test-image"], "test.png", {
+        type: "image/png",
+      });
+      const mediaFile = new File(["test-media"], "test.mp4", {
+        type: "video/mp4",
+      });
+
+      builder
+        .withName("Test Coin")
+        .withSymbol("TEST")
+        .withDescription("Test Description")
+        .withImage(imageFile)
+        .withMedia(mediaFile)
+        .withProperties({ key1: "value1", key2: "value2" });
+
+      const result = await builder.upload(mockUploaderData.uploader);
+
+      // Verify uploader was called 3 times
+      expect(mockUploaderData.uploader.upload).toHaveBeenCalledTimes(3);
+
+      // Verify files were uploaded in the right order
+      expect(mockUploaderData.uploadedFiles[0]).toBe(imageFile);
+      expect(mockUploaderData.uploadedFiles[1]).toBe(mediaFile);
+      expect(mockUploaderData.uploadedFiles[2]?.type).toBe("application/json");
+
+      // Verify result
+      expect(result.url.toString()).toBe("ipfs://metadata-cid");
+    });
+
+    it("should use existing image and media URLs if provided", async () => {
+      mockUploaderData = createMockUploader([UploadResultType.Metadata]);
+      builder = new CoinMetadataBuilder();
+
+      builder
+        .withName("Test Coin")
+        .withSymbol("TEST")
+        .withDescription("Test Description")
+        .withImageURI("ipfs://existing-image")
+        .withMediaURI("ipfs://existing-media", "video/mp4")
+        .withProperties({ key1: "value1", key2: "value2" });
+
+      const result = await builder.upload(mockUploaderData.uploader);
+
+      // Should only upload metadata (1 upload)
+      expect(mockUploaderData.uploader.upload).toHaveBeenCalledTimes(1);
+
+      // The upload should be the metadata
+      expect(mockUploaderData.uploadedFiles[0]?.type).toBe("application/json");
+
+      // Verify result
+      expect(result.url.toString()).toBe("ipfs://metadata-cid");
+    });
+
+    it("should validate before uploading", async () => {
+      // Missing required fields
+      builder.withName("Test Coin");
+
+      await expect(builder.upload(mockUploaderData.uploader)).rejects.toThrow(
+        "Symbol is required",
+      );
+    });
+  });
+});