feat: Include embedUrl in .create return

Author: bprusinowski

README.md

@@ -49,10 +49,10 @@ const png = await szum.render({
 
 ## Saved charts
 
-Save a config server-side and embed the returned short URL in an `<img>` tag (Pro plan):
+Save a config server-side and embed the returned short URL in an `<img>` tag, or drop the embed URL into an `<iframe>` for an interactive version (Pro plan):
 
 ```typescript
-const { url, id } = await szum.charts.create({
+const { url, embedUrl, id } = await szum.charts.create({
   format: "svg",
   theme: "editorial",
   marks: [
@@ -66,11 +66,12 @@ const { url, id } = await szum.charts.create({
   ],
 });
 
-// Use in HTML: <img src={url} />
+// Static image: <img src={url} />
+// Interactive embed: <iframe src={embedUrl} />
 // Revoke later: await szum.charts.delete(id);
 ```
 
-The returned URL points at `https://szum.io/c/<id>` and renders the same chart on every fetch.
+`url` points at `https://szum.io/c/<id>` and renders the same chart image on every fetch. `embedUrl` points at `https://szum.io/e/<id>` and serves an interactive HTML page with tooltips, legend toggle, and responsive resize.
 
 ## Configuration
 

src/charts.ts

@@ -22,7 +22,7 @@ export class SzumCharts {
   async create(
     config: ChartConfig,
     options?: RequestOptions,
-  ): Promise<{ url: string; id: string }> {
+  ): Promise<{ url: string; embedUrl: string; id: string }> {
     const response = await this.api.request(
       "/api/charts",
       {
@@ -34,9 +34,10 @@ export class SzumCharts {
 
     const obj = await parseJsonObject(response);
     const url = requireString(obj, "url", response);
+    const embedUrl = requireString(obj, "embedUrl", response);
     const id = requireString(obj, "id", response);
 
-    return { url, id };
+    return { url, embedUrl, id };
   }
 
   async delete(id: string, options?: RequestOptions): Promise<void> {

src/client.test.ts

@@ -84,12 +84,16 @@ describe("Szum (integration)", () => {
 
   describe("charts.create", () => {
     it.skipIf(!HAS_API_KEY)(
-      "returns { url, id } for a valid config",
+      "returns { url, embedUrl, id } for a valid config",
       async () => {
         const result = await szum.charts.create(VALID_CONFIG);
 
         expect(typeof result.url).toBe("string");
         expect(result.url).toMatch(/^https?:\/\//);
+        expect(result.url).toContain("/c/");
+        expect(typeof result.embedUrl).toBe("string");
+        expect(result.embedUrl).toMatch(/^https?:\/\//);
+        expect(result.embedUrl).toContain("/e/");
         expect(typeof result.id).toBe("string");
         expect(result.id.length).toBeGreaterThan(0);
       },

src/client.unit.test.ts

@@ -387,6 +387,7 @@ describe("Szum (unit)", () => {
         createMockResponse({
           body: JSON.stringify({
             url: "https://szum.io/c/abc123",
+            embedUrl: "https://szum.io/e/abc123",
             id: "abc123",
           }),
         }),
@@ -403,22 +404,31 @@ describe("Szum (unit)", () => {
       expect(body.config).toEqual({ ...VALID_CONFIG, version: SCHEMA_VERSION });
     });
 
-    it("returns { url, id } on success", async () => {
+    it("returns { url, embedUrl, id } on success", async () => {
       const szum = new Szum({
         apiKey: "sk_test",
         baseUrl: "https://test.szum.io",
       });
       const expectedUrl = "https://szum.io/c/abc123";
+      const expectedEmbedUrl = "https://szum.io/e/abc123";
       const expectedId = "abc123";
       fetchMock.mockResolvedValue(
         createMockResponse({
-          body: JSON.stringify({ url: expectedUrl, id: expectedId }),
+          body: JSON.stringify({
+            url: expectedUrl,
+            embedUrl: expectedEmbedUrl,
+            id: expectedId,
+          }),
         }),
       );
 
       const result = await szum.charts.create(VALID_CONFIG);
 
-      expect(result).toEqual({ url: expectedUrl, id: expectedId });
+      expect(result).toEqual({
+        url: expectedUrl,
+        embedUrl: expectedEmbedUrl,
+        id: expectedId,
+      });
     });
 
     it("throws SzumAPIError when response is missing 'url'", async () => {
@@ -428,7 +438,10 @@ describe("Szum (unit)", () => {
       });
       fetchMock.mockResolvedValue(
         createMockResponse({
-          body: JSON.stringify({ id: "abc123" }),
+          body: JSON.stringify({
+            embedUrl: "https://szum.io/e/abc123",
+            id: "abc123",
+          }),
         }),
       );
 
@@ -441,14 +454,40 @@ describe("Szum (unit)", () => {
       }
     });
 
+    it("throws SzumAPIError when response is missing 'embedUrl'", async () => {
+      const szum = new Szum({
+        apiKey: "sk_test",
+        baseUrl: "https://test.szum.io",
+      });
+      fetchMock.mockResolvedValue(
+        createMockResponse({
+          body: JSON.stringify({
+            url: "https://szum.io/c/abc123",
+            id: "abc123",
+          }),
+        }),
+      );
+
+      try {
+        await szum.charts.create(VALID_CONFIG);
+        expect.unreachable("should have thrown");
+      } catch (err) {
+        expect(err).toBeInstanceOf(SzumAPIError);
+        expect((err as SzumError).message).toMatch(/missing 'embedUrl'/);
+      }
+    });
+
     it("throws SzumAPIError when response is missing 'id'", async () => {
       const szum = new Szum({
         apiKey: "sk_test",
         baseUrl: "https://test.szum.io",
       });
       fetchMock.mockResolvedValue(
         createMockResponse({
-          body: JSON.stringify({ url: "https://szum.io/c/abc123" }),
+          body: JSON.stringify({
+            url: "https://szum.io/c/abc123",
+            embedUrl: "https://szum.io/e/abc123",
+          }),
         }),
       );