From 01ecde3bfa7bc9d3ba674bcdaf053077c7d60a25 Mon Sep 17 00:00:00 2001
From: Andrey Antukh <niwi@niwi.nz>
Date: Mon, 22 Dec 2025 20:55:31 +0100
Subject: [PATCH] :sparkles: Add the ability to add relations on penpot sdk
 (#7987)

* :sparkles: Add the ability to add relations on penpot sdk

* :paperclip: Remove debug console log
---
 library/CHANGES.md                     |  6 ++++++
 library/package.json                   |  4 ++--
 library/playground/sample-relations.js | 30 ++++++++++++++++++++++++++
 library/src/lib/builder.cljs           | 13 ++++++++++-
 library/src/lib/export.cljs            |  3 ++-
 library/test/builder.test.js           | 27 +++++++++++++++++++++++
 6 files changed, 79 insertions(+), 4 deletions(-)
 create mode 100644 library/playground/sample-relations.js

diff --git a/library/CHANGES.md b/library/CHANGES.md
index e136c7759c..ac3e4ca0bd 100644
--- a/library/CHANGES.md
+++ b/library/CHANGES.md
@@ -1,5 +1,11 @@
 # CHANGELOG
 
+
+## 1.2.0-RC1
+
+- Add the ability to add relations (with `addRelation` method)
+
+
 ## 1.1.0
 
 - Same as 1.1.0-RC2
diff --git a/library/package.json b/library/package.json
index 3eb2bac236..ab32814487 100644
--- a/library/package.json
+++ b/library/package.json
@@ -1,9 +1,9 @@
 {
   "name": "@penpot/library",
-  "version": "1.1.0",
+  "version": "1.2.0-RC1",
   "license": "MPL-2.0",
   "author": "Kaleidos INC",
-  "packageManager": "yarn@4.11.0+sha512.4e54aeace9141df2f0177c266b05ec50dc044638157dae128c471ba65994ac802122d7ab35bcd9e81641228b7dcf24867d28e750e0bcae8a05277d600008ad54",
+  "packageManager": "yarn@4.12.0+sha512.f45ab632439a67f8bc759bf32ead036a1f413287b9042726b7cc4818b7b49e14e9423ba49b18f9e06ea4941c1ad062385b1d8760a8d5091a1a31e5f6219afca8",
   "type": "module",
   "repository": {
     "type": "git",
diff --git a/library/playground/sample-relations.js b/library/playground/sample-relations.js
new file mode 100644
index 0000000000..ab2350c812
--- /dev/null
+++ b/library/playground/sample-relations.js
@@ -0,0 +1,30 @@
+import * as penpot from "#self";
+import { writeFile, readFile } from "fs/promises";
+
+(async function () {
+  const context = penpot.createBuildContext();
+
+  {
+    const file1 = context.addFile({ name: "Test File 1" });
+    const file2 = context.addFile({ name: "Test File 1" });
+
+    context.addRelation(file1, file2);
+  }
+
+  {
+    let result = await penpot.exportAsBytes(context);
+    await writeFile("sample-relations.zip", result);
+  }
+})()
+  .catch((cause) => {
+    console.error(cause);
+
+    const innerCause = cause.cause;
+    if (innerCause) {
+      console.error("Inner cause:", innerCause);
+    }
+    process.exit(-1);
+  })
+  .finally(() => {
+    process.exit(0);
+  });
diff --git a/library/src/lib/builder.cljs b/library/src/lib/builder.cljs
index 316631d8d4..4cc8cc97e0 100644
--- a/library/src/lib/builder.cljs
+++ b/library/src/lib/builder.cljs
@@ -87,7 +87,8 @@
       (try
         (let [params (-> params decode-params fb/decode-file)]
           (-> (swap! state fb/add-file params)
-              (get ::fb/current-file-id)))
+              (get ::fb/current-file-id)
+              (dm/str)))
         (catch :default cause
           (handle-exception cause))))
 
@@ -273,6 +274,16 @@
         (catch :default cause
           (handle-exception cause))))
 
+    :addRelation
+    (fn [file-id library-id]
+      (let [file-id    (uuid/parse file-id)
+            library-id (uuid/parse library-id)]
+        (if (and file-id library-id)
+          (do
+            (swap! state update :relations assoc file-id library-id)
+            true)
+          false)))
+
     :genId
     (fn []
       (dm/str (uuid/next)))
diff --git a/library/src/lib/export.cljs b/library/src/lib/export.cljs
index 72c779c24e..1c0e883d0e 100644
--- a/library/src/lib/export.cljs
+++ b/library/src/lib/export.cljs
@@ -194,7 +194,8 @@
                 :generated-by "penpot-library/%version%"
                 :referer (get opts :referer)
                 :files files
-                :relations []}
+                :relations (->> (:relations state)
+                                (mapv vec))}
         params (d/without-nils params)]
 
     ["manifest.json"
diff --git a/library/test/builder.test.js b/library/test/builder.test.js
index 207f863e35..e4c7bf8a37 100644
--- a/library/test/builder.test.js
+++ b/library/test/builder.test.js
@@ -54,6 +54,33 @@ test("create context with two file", () => {
   assert.equal(file.data.pages.length, 0)
 });
 
+test("create context with two file and relation between", () => {
+  const context = penpot.createBuildContext();
+
+  const fileId_1 = context.addFile({name: "sample 1"});
+  const fileId_2 = context.addFile({name: "sample 2"});
+
+  context.addRelation(fileId_1, fileId_2);
+
+  const internalState = context.getInternalState();
+
+  assert.ok(internalState.files[fileId_1]);
+  assert.ok(internalState.files[fileId_2]);
+  assert.equal(internalState.files[fileId_1].name, "sample 1");
+  assert.equal(internalState.files[fileId_2].name, "sample 2");
+
+  assert.ok(internalState.relations[fileId_1]);
+  assert.equal(internalState.relations[fileId_1], fileId_2);
+
+  const file = internalState.files[fileId_2];
+
+  assert.ok(file.data);
+  assert.ok(file.data.pages);
+  assert.ok(file.data.pagesIndex);
+  assert.equal(file.data.pages.length, 0)
+});
+
+
 test("create context with file and page", () => {
   const context = penpot.createBuildContext();