@storyshelf/design-figma 0.0.0-stage → 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @storyshelf/design-figma
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Figma design provider for StoryShelf: validates Figma links, reads file/node metadata (name, version, last modified) and downloads rendered previews through the Figma REST API with a personal access token.
+
+## Install
+
+```sh
+nub add @storyshelf/design-figma
+```
+
+or
+
+```sh
+npm install @storyshelf/design-figma
+```
+
+## Quick start
+
+```ts
+import { createShelfApp } from "@storyshelf/app";
+import { createFigmaDesign } from "@storyshelf/design-figma";
+
+const app = createShelfApp({
+  database,
+  storage,
+  testing: { runner: captureRunner },
+  design: [createFigmaDesign()],
+  config: {
+    secret: process.env.SHELF_SECRET, // also encrypts the Figma token
+  },
+});
+```
+
+Without a provider, StoryShelf extracts and shows no design links. With it, stories link to Figma through `parameters.storyshelf.figma` or the Storybook `design` addon, and project admins manage mappings and the access token under **Settings → Design**. See [Design links](https://storyshelf.js.org/guides/design-links/) for how stories, mappings and the access token work.
+
+## Let members connect their own account
+
+Without a project token, a member can connect their own Figma account (like Jira or Linear integrations) and see previews, names and stale-design warnings with their own access. Register an OAuth app in Figma (**Settings → OAuth apps**; a private app works within your organization), add the redirect URL `<publicBaseUrl>/connections/figma/callback` and the `file_content:read` scope, then:
+
+```ts
+import { createFigmaDesign, figmaOAuthFromEnv } from "@storyshelf/design-figma";
+
+design: [createFigmaDesign({ oauth: figmaOAuthFromEnv() })], // FIGMA_CLIENT_ID / FIGMA_CLIENT_SECRET
+```
+
+This needs authentication enabled and `config.secret` (it signs the connect flow and encrypts tokens). A project token, when set, always takes precedence; a member's token is used only while they view a page, and what it fetches is shown only to them.
+
+## Accepted links
+
+`https://www.figma.com/{file|design|board|proto|make}/<key>/…` with an optional `node-id`. Embed, community and Figma Sites links are rejected.

package/dist/api.d.mts

@@ -0,0 +1,23 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DesignCallOptions, DesignClient, DesignMeta, DesignRef } from "@storyshelf/core/adapter/design";
+import { Buffer } from "node:buffer";
+//#region src/api.d.ts
+/** A Figma client bound to a personal access token (or, with `authType: "oauth"`, a user's OAuth token). */
+declare function createFigmaClient(credential: string, authType?: "token" | "oauth"): DesignClient;
+/**
+ * Fetch metadata for several refs of one file in at most two requests: one
+ * `nodes?ids=a,b` call for every node ref and one depth-1 file call when the
+ * whole file is linked. API failures map to a state per ref.
+ */
+declare function fetchFigmaMetas(token: string, fileKey: string, refs: readonly DesignRef[], options?: DesignCallOptions): Promise<Map<string, DesignMeta>>;
+/**
+ * Render several nodes of one file to PNG with a single Images API call, then
+ * download each (Figma's signed URLs expire, so they are never hot-linked).
+ * Nodes Figma has no render for, or whose download fails, are omitted.
+ * Throws when the Images API call itself fails.
+ */
+declare function fetchFigmaRenders(token: string, fileKey: string, nodeIds: readonly string[], options?: DesignCallOptions): Promise<Map<string, Buffer>>;
+//#endregion
+export { createFigmaClient, fetchFigmaMetas, fetchFigmaRenders };
+//# sourceMappingURL=api.d.mts.map

package/dist/api.mjs

@@ -0,0 +1,131 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { HttpError, httpBytes, httpJson } from "@storyshelf/core/utils";
+//#region src/api.ts
+const FIGMA_API = "https://api.figma.com/v1";
+/**
+* Render scale: 2x keeps text legible next to retina screenshots without the
+* 4x payload; renders are reference-only, never diffed.
+*/
+const RENDER_SCALE = 2;
+const EMPTY = {
+	name: null,
+	version: null,
+	lastModified: null
+};
+/** Marks an OAuth access token: sent as `Authorization: Bearer`, where a personal token uses `X-Figma-Token`. */
+const BEARER = "Bearer ";
+/** A Figma client bound to a personal access token (or, with `authType: "oauth"`, a user's OAuth token). */
+function createFigmaClient(credential, authType = "token") {
+	const token = authType === "oauth" ? `${BEARER}${credential}` : credential;
+	return {
+		fetchMetas: async (fileKey, refs, options) => await fetchFigmaMetas(token, fileKey, refs, options),
+		fetchRenders: async (fileKey, nodeIds, options) => await fetchFigmaRenders(token, fileKey, nodeIds, options)
+	};
+}
+function requestOptions(token, timeoutMs, options) {
+	return {
+		headers: token.startsWith(BEARER) ? { Authorization: token } : { "X-Figma-Token": token },
+		timeoutMs,
+		retries: 2,
+		...options.logger ? { logger: options.logger } : {},
+		...options.signal ? { signal: options.signal } : {}
+	};
+}
+/**
+* Fetch metadata for several refs of one file in at most two requests: one
+* `nodes?ids=a,b` call for every node ref and one depth-1 file call when the
+* whole file is linked. API failures map to a state per ref.
+*/
+async function fetchFigmaMetas(token, fileKey, refs, options = {}) {
+	const ids = [...new Set(refs.flatMap((ref) => ref.nodeId ? [ref.nodeId] : []))];
+	const results = ids.length > 0 ? await fetchNodeMetas(token, fileKey, ids, options) : /* @__PURE__ */ new Map();
+	if (refs.some((ref) => !ref.nodeId)) results.set("", await fetchFileMeta(token, fileKey, options));
+	return results;
+}
+/** One `nodes?ids=a,b` request answering for every node id. */
+async function fetchNodeMetas(token, fileKey, ids, options) {
+	const outcome = await fetchOrFail(`${FIGMA_API}/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(ids.join(","))}&depth=1`, token, options);
+	return new Map(ids.map((id) => [id, "meta" in outcome ? nodeMeta(outcome.meta, id) : outcome]));
+}
+async function fetchFileMeta(token, fileKey, options) {
+	const outcome = await fetchOrFail(`${FIGMA_API}/files/${encodeURIComponent(fileKey)}?depth=1`, token, options);
+	return "meta" in outcome ? fileMeta(outcome.meta) : outcome;
+}
+async function fetchOrFail(url, token, options) {
+	try {
+		return { meta: await httpJson(url, requestOptions(token, 1e4, options)) };
+	} catch (error) {
+		return failureMeta(error);
+	}
+}
+function fileMeta(body) {
+	return {
+		state: "ok",
+		name: body.name ?? null,
+		version: body.version ?? null,
+		lastModified: body.lastModified ?? null
+	};
+}
+function nodeMeta(body, id) {
+	const base = {
+		version: body.version ?? null,
+		lastModified: body.lastModified ?? null
+	};
+	const node = body.nodes?.[id];
+	if (!node) return {
+		state: "deleted",
+		name: null,
+		...base
+	};
+	return {
+		state: "ok",
+		name: node.document?.name ?? body.name ?? null,
+		...base
+	};
+}
+function failureMeta(error) {
+	if (error instanceof HttpError) {
+		if (error.status === 401) return {
+			state: "unauthorized",
+			...EMPTY
+		};
+		if (error.status === 403) return {
+			state: "forbidden",
+			...EMPTY
+		};
+		if (error.status === 404) return {
+			state: "deleted",
+			...EMPTY
+		};
+	}
+	return {
+		state: "error",
+		...EMPTY
+	};
+}
+/**
+* Render several nodes of one file to PNG with a single Images API call, then
+* download each (Figma's signed URLs expire, so they are never hot-linked).
+* Nodes Figma has no render for, or whose download fails, are omitted.
+* Throws when the Images API call itself fails.
+*/
+async function fetchFigmaRenders(token, fileKey, nodeIds, options = {}) {
+	if (nodeIds.length === 0) return /* @__PURE__ */ new Map();
+	const ids = encodeURIComponent(nodeIds.join(","));
+	const body = await httpJson(`${FIGMA_API}/images/${encodeURIComponent(fileKey)}?ids=${ids}&format=png&scale=${RENDER_SCALE}`, requestOptions(token, 15e3, options));
+	const downloaded = await Promise.all(nodeIds.map(async (id) => {
+		const url = body.images?.[id];
+		return url ? [id, await download(url, options)] : null;
+	}));
+	return new Map(downloaded.filter((entry) => entry !== null));
+}
+async function download(url, options) {
+	const { headers: _headers, ...rest } = requestOptions("", 3e4, options);
+	return await httpBytes(url, rest);
+}
+//#endregion
+export { createFigmaClient, fetchFigmaMetas, fetchFigmaRenders };
+
+//# sourceMappingURL=api.mjs.map

package/dist/api.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.mjs","names":[],"sources":["../src/api.ts"],"sourcesContent":["/** Figma REST client: batched metadata and render fetches with a personal access token, via the shared HTTP helper. */\nimport type {\n  DesignCallOptions,\n  DesignClient,\n  DesignMeta,\n  DesignRef,\n} from \"@storyshelf/core/adapter/design\";\nimport { HttpError, httpBytes, httpJson, type HttpRequestOptions } from \"@storyshelf/core/utils\";\nimport type { Buffer } from \"node:buffer\";\n\nconst FIGMA_API = \"https://api.figma.com/v1\";\n/**\n * Render scale: 2x keeps text legible next to retina screenshots without the\n * 4x payload; renders are reference-only, never diffed.\n */\nconst RENDER_SCALE = 2;\n\ninterface FileResponse {\n  name?: string;\n  version?: string;\n  lastModified?: string;\n}\ninterface NodesResponse extends FileResponse {\n  nodes?: Record<string, { document?: { name?: string } } | null>;\n}\ninterface ImagesResponse {\n  images?: Record<string, string | null>;\n}\n\nconst EMPTY = { name: null, version: null, lastModified: null } as const;\n\n/** Marks an OAuth access token: sent as `Authorization: Bearer`, where a personal token uses `X-Figma-Token`. */\nconst BEARER = \"Bearer \";\n\n/** A Figma client bound to a personal access token (or, with `authType: \"oauth\"`, a user's OAuth token). */\nexport function createFigmaClient(\n  credential: string,\n  authType: \"token\" | \"oauth\" = \"token\",\n): DesignClient {\n  const token = authType === \"oauth\" ? `${BEARER}${credential}` : credential;\n  return {\n    fetchMetas: async (fileKey, refs, options) =>\n      await fetchFigmaMetas(token, fileKey, refs, options),\n    fetchRenders: async (fileKey, nodeIds, options) =>\n      await fetchFigmaRenders(token, fileKey, nodeIds, options),\n  };\n}\n\nfunction requestOptions(\n  token: string,\n  timeoutMs: number,\n  options: DesignCallOptions,\n): HttpRequestOptions {\n  return {\n    headers: token.startsWith(BEARER) ? { Authorization: token } : { \"X-Figma-Token\": token },\n    timeoutMs,\n    // `retries` is the total attempt count (first try included), so 2 = one retry; the shared default is 3.\n    retries: 2,\n    ...(options.logger ? { logger: options.logger } : {}),\n    ...(options.signal ? { signal: options.signal } : {}),\n  };\n}\n\n/**\n * Fetch metadata for several refs of one file in at most two requests: one\n * `nodes?ids=a,b` call for every node ref and one depth-1 file call when the\n * whole file is linked. API failures map to a state per ref.\n */\nexport async function fetchFigmaMetas(\n  token: string,\n  fileKey: string,\n  refs: readonly DesignRef[],\n  options: DesignCallOptions = {},\n): Promise<Map<string, DesignMeta>> {\n  const ids = [...new Set(refs.flatMap((ref) => (ref.nodeId ? [ref.nodeId] : [])))];\n  const results = ids.length > 0 ? await fetchNodeMetas(token, fileKey, ids, options) : new Map();\n  if (refs.some((ref) => !ref.nodeId)) {\n    results.set(\"\", await fetchFileMeta(token, fileKey, options));\n  }\n  return results;\n}\n\n/** One `nodes?ids=a,b` request answering for every node id. */\nasync function fetchNodeMetas(\n  token: string,\n  fileKey: string,\n  ids: readonly string[],\n  options: DesignCallOptions,\n): Promise<Map<string, DesignMeta>> {\n  const key = encodeURIComponent(fileKey);\n  const url = `${FIGMA_API}/files/${key}/nodes?ids=${encodeURIComponent(ids.join(\",\"))}&depth=1`;\n  const outcome = await fetchOrFail<NodesResponse>(url, token, options);\n  return new Map(ids.map((id) => [id, \"meta\" in outcome ? nodeMeta(outcome.meta, id) : outcome]));\n}\n\nasync function fetchFileMeta(\n  token: string,\n  fileKey: string,\n  options: DesignCallOptions,\n): Promise<DesignMeta> {\n  const url = `${FIGMA_API}/files/${encodeURIComponent(fileKey)}?depth=1`;\n  const outcome = await fetchOrFail<FileResponse>(url, token, options);\n  return \"meta\" in outcome ? fileMeta(outcome.meta) : outcome;\n}\n\ntype Fetched<T> = { meta: T } | DesignMeta;\n\nasync function fetchOrFail<T>(\n  url: string,\n  token: string,\n  options: DesignCallOptions,\n): Promise<Fetched<T>> {\n  try {\n    return { meta: await httpJson<T>(url, requestOptions(token, 10_000, options)) };\n  } catch (error) {\n    return failureMeta(error);\n  }\n}\n\nfunction fileMeta(body: FileResponse): DesignMeta {\n  return {\n    state: \"ok\",\n    name: body.name ?? null,\n    version: body.version ?? null,\n    lastModified: body.lastModified ?? null,\n  };\n}\n\nfunction nodeMeta(body: NodesResponse, id: string): DesignMeta {\n  const base = { version: body.version ?? null, lastModified: body.lastModified ?? null };\n  const node = body.nodes?.[id];\n  if (!node) return { state: \"deleted\", name: null, ...base };\n  return { state: \"ok\", name: node.document?.name ?? body.name ?? null, ...base };\n}\n\nfunction failureMeta(error: unknown): DesignMeta {\n  if (error instanceof HttpError) {\n    if (error.status === 401) return { state: \"unauthorized\", ...EMPTY };\n    if (error.status === 403) return { state: \"forbidden\", ...EMPTY };\n    if (error.status === 404) return { state: \"deleted\", ...EMPTY };\n  }\n  return { state: \"error\", ...EMPTY };\n}\n\n/**\n * Render several nodes of one file to PNG with a single Images API call, then\n * download each (Figma's signed URLs expire, so they are never hot-linked).\n * Nodes Figma has no render for, or whose download fails, are omitted.\n * Throws when the Images API call itself fails.\n */\nexport async function fetchFigmaRenders(\n  token: string,\n  fileKey: string,\n  nodeIds: readonly string[],\n  options: DesignCallOptions = {},\n): Promise<Map<string, Buffer>> {\n  if (nodeIds.length === 0) return new Map();\n  const ids = encodeURIComponent(nodeIds.join(\",\"));\n  const body = await httpJson<ImagesResponse>(\n    `${FIGMA_API}/images/${encodeURIComponent(fileKey)}?ids=${ids}&format=png&scale=${RENDER_SCALE}`,\n    requestOptions(token, 15_000, options),\n  );\n  const downloaded = await Promise.all(\n    nodeIds.map(async (id) => {\n      const url = body.images?.[id];\n      return url ? ([id, await download(url, options)] as const) : null;\n    }),\n  );\n  return new Map(downloaded.filter((entry) => entry !== null));\n}\n\nasync function download(url: string, options: DesignCallOptions): Promise<Buffer> {\n  const { headers: _headers, ...rest } = requestOptions(\"\", 30_000, options);\n  return await httpBytes(url, rest);\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { FigmaOAuthOptions, createFigmaOAuth, figmaOAuthFromEnv } from "./oauth.mjs";
+import { createFigmaClient, fetchFigmaMetas, fetchFigmaRenders } from "./api.mjs";
+import { parseFigmaUrl } from "./url.mjs";
+import { DesignProvider } from "@storyshelf/core/adapter/design";
+//#region src/index.d.ts
+/** Options of {@link createFigmaDesign}. */
+interface FigmaDesignOptions {
+  /** Registered Figma OAuth app: lets members connect their own account when the project has no token. */
+  oauth?: FigmaOAuthOptions;
+}
+/** Figma design provider for StoryShelf: pass it as `design: [createFigmaDesign()]`. */
+declare function createFigmaDesign(options?: FigmaDesignOptions): DesignProvider;
+//#endregion
+export { FigmaDesignOptions, type FigmaOAuthOptions, createFigmaClient, createFigmaDesign, createFigmaOAuth, fetchFigmaMetas, fetchFigmaRenders, figmaOAuthFromEnv, parseFigmaUrl };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,21 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { createFigmaClient, fetchFigmaMetas, fetchFigmaRenders } from "./api.mjs";
+import { getMetadata } from "./metadata.mjs";
+import { createFigmaOAuth, figmaOAuthFromEnv } from "./oauth.mjs";
+import { parseFigmaUrl } from "./url.mjs";
+//#region src/index.ts
+/** Figma design provider for StoryShelf: pass it as `design: [createFigmaDesign()]`. */
+function createFigmaDesign(options = {}) {
+	return {
+		metadata: getMetadata(),
+		parseUrl: parseFigmaUrl,
+		create: ({ credential, authType }) => createFigmaClient(credential, authType),
+		...options.oauth ? { oauth: createFigmaOAuth(options.oauth) } : {}
+	};
+}
+//#endregion
+export { createFigmaClient, createFigmaDesign, createFigmaOAuth, fetchFigmaMetas, fetchFigmaRenders, figmaOAuthFromEnv, parseFigmaUrl };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { DesignProvider } from \"@storyshelf/core/adapter/design\";\nimport { createFigmaClient } from \"./api.ts\";\nimport { getMetadata } from \"./metadata.ts\";\nimport { createFigmaOAuth, type FigmaOAuthOptions } from \"./oauth.ts\";\nimport { parseFigmaUrl } from \"./url.ts\";\n\n/** Options of {@link createFigmaDesign}. */\nexport interface FigmaDesignOptions {\n  /** Registered Figma OAuth app: lets members connect their own account when the project has no token. */\n  oauth?: FigmaOAuthOptions;\n}\n\n/** Figma design provider for StoryShelf: pass it as `design: [createFigmaDesign()]`. */\nexport function createFigmaDesign(options: FigmaDesignOptions = {}): DesignProvider {\n  return {\n    metadata: getMetadata(),\n    parseUrl: parseFigmaUrl,\n    create: ({ credential, authType }) => createFigmaClient(credential, authType),\n    ...(options.oauth ? { oauth: createFigmaOAuth(options.oauth) } : {}),\n  };\n}\n\nexport { createFigmaClient, fetchFigmaMetas, fetchFigmaRenders } from \"./api.ts\";\nexport { createFigmaOAuth, figmaOAuthFromEnv, type FigmaOAuthOptions } from \"./oauth.ts\";\nexport { parseFigmaUrl } from \"./url.ts\";\n"],"mappings":";;;;;;;;;AAaA,SAAgB,kBAAkB,UAA8B,CAAC,GAAmB;CAClF,OAAO;EACL,UAAU,YAAY;EACtB,UAAU;EACV,SAAS,EAAE,YAAY,eAAe,kBAAkB,YAAY,QAAQ;EAC5E,GAAI,QAAQ,QAAQ,EAAE,OAAO,iBAAiB,QAAQ,KAAK,EAAE,IAAI,CAAC;CACpE;AACF"}

package/dist/metadata.mjs

@@ -0,0 +1,23 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/metadata.ts
+/** Describe the Figma provider (name, version, credential copy). */
+function getMetadata() {
+	return {
+		name: "Figma",
+		version: "0.7.0",
+		description: "Figma links, file metadata and rendered previews via the Figma REST API",
+		kind: "figma",
+		category: "design",
+		credentialLabel: "Figma access token",
+		credentialHelp: "A personal access token with read access (file content) lets StoryShelf show the design name and flag stale designs. Without one, buttons still deep-link to Figma. Figma tokens expire after at most 90 days — rotate before then.",
+		credentialPlaceholder: "figd_…",
+		urlHint: "https://www.figma.com/design/<file>?node-id=1-2",
+		credentialMaxAgeDays: 90
+	};
+}
+//#endregion
+export { getMetadata };
+
+//# sourceMappingURL=metadata.mjs.map

package/dist/metadata.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.mjs","names":[],"sources":["../src/metadata.ts"],"sourcesContent":["import type { DesignProvider } from \"@storyshelf/core/adapter/design\";\n\ndeclare const __PKG_VERSION__: string | undefined;\n\n/** Describe the Figma provider (name, version, credential copy). */\nexport function getMetadata(): DesignProvider[\"metadata\"] {\n  return {\n    name: \"Figma\",\n    version: typeof __PKG_VERSION__ === \"string\" ? __PKG_VERSION__ : \"0.0.0\",\n    description: \"Figma links, file metadata and rendered previews via the Figma REST API\",\n    kind: \"figma\",\n    category: \"design\",\n    credentialLabel: \"Figma access token\",\n    credentialHelp:\n      \"A personal access token with read access (file content) lets StoryShelf show the design name and flag stale designs. Without one, buttons still deep-link to Figma. Figma tokens expire after at most 90 days — rotate before then.\",\n    credentialPlaceholder: \"figd_…\",\n    urlHint: \"https://www.figma.com/design/<file>?node-id=1-2\",\n    credentialMaxAgeDays: 90,\n  };\n}\n"],"mappings":";;;;;AAKA,SAAgB,cAA0C;CACxD,OAAO;EACL,MAAM;EACN,SAAA;EACA,aAAa;EACb,MAAM;EACN,UAAU;EACV,iBAAiB;EACjB,gBACE;EACF,uBAAuB;EACvB,SAAS;EACT,sBAAsB;CACxB;AACF"}

package/dist/oauth.d.mts

@@ -0,0 +1,16 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { OAuthClient } from "@storyshelf/core/adapter/oauth";
+//#region src/oauth.d.ts
+/** Operator-registered Figma OAuth app (Figma → Settings → OAuth apps). */
+interface FigmaOAuthOptions {
+  clientId: string;
+  clientSecret: string;
+}
+/** OAuth app credentials from `FIGMA_CLIENT_ID` / `FIGMA_CLIENT_SECRET`, or undefined when either is unset. */
+declare function figmaOAuthFromEnv(env?: Record<string, string | undefined>): FigmaOAuthOptions | undefined;
+/** Figma's {@link OAuthClient} for one registered OAuth app. */
+declare function createFigmaOAuth(options: FigmaOAuthOptions): OAuthClient;
+//#endregion
+export { FigmaOAuthOptions, createFigmaOAuth, figmaOAuthFromEnv };
+//# sourceMappingURL=oauth.d.mts.map

package/dist/oauth.mjs

@@ -0,0 +1,64 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { httpJson } from "@storyshelf/core/utils";
+//#region src/oauth.ts
+const AUTHORIZE_URL = "https://www.figma.com/oauth";
+const TOKEN_URL = "https://api.figma.com/v1/oauth/token";
+const REFRESH_URL = "https://api.figma.com/v1/oauth/refresh";
+/** Read-only: file content (names, versions, renders). */
+const SCOPE = "file_content:read";
+/** Figma issues 90-day access tokens; used when a response omits `expires_in`. */
+const DEFAULT_EXPIRES_S = 7776e3;
+/** OAuth app credentials from `FIGMA_CLIENT_ID` / `FIGMA_CLIENT_SECRET`, or undefined when either is unset. */
+function figmaOAuthFromEnv(env = process.env) {
+	const clientId = env["FIGMA_CLIENT_ID"];
+	const clientSecret = env["FIGMA_CLIENT_SECRET"];
+	return clientId && clientSecret ? {
+		clientId,
+		clientSecret
+	} : void 0;
+}
+/** Figma's {@link OAuthClient} for one registered OAuth app. */
+function createFigmaOAuth(options) {
+	const basic = `Basic ${Buffer.from(`${options.clientId}:${options.clientSecret}`).toString("base64")}`;
+	const post = async (url, form, signal) => {
+		return toTokens(await httpJson(url, {
+			method: "POST",
+			headers: { Authorization: basic },
+			form,
+			retries: 1,
+			...signal ? { signal } : {}
+		}));
+	};
+	return {
+		authorizeUrl: ({ state, redirectUri }) => {
+			const params = new URLSearchParams({
+				client_id: options.clientId,
+				redirect_uri: redirectUri,
+				scope: SCOPE,
+				state,
+				response_type: "code"
+			});
+			return `${AUTHORIZE_URL}?${params.toString()}`;
+		},
+		exchangeCode: async ({ code, redirectUri, signal }) => await post(TOKEN_URL, {
+			redirect_uri: redirectUri,
+			code,
+			grant_type: "authorization_code"
+		}, signal),
+		refresh: async ({ refreshToken, signal }) => await post(REFRESH_URL, { refresh_token: refreshToken }, signal)
+	};
+}
+function toTokens(response) {
+	const seconds = response.expires_in ?? DEFAULT_EXPIRES_S;
+	return {
+		accessToken: response.access_token,
+		refreshToken: response.refresh_token ?? null,
+		expiresAt: new Date(Date.now() + seconds * 1e3).toISOString()
+	};
+}
+//#endregion
+export { createFigmaOAuth, figmaOAuthFromEnv };
+
+//# sourceMappingURL=oauth.mjs.map

package/dist/oauth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.mjs","names":[],"sources":["../src/oauth.ts"],"sourcesContent":["/** Figma OAuth 2 (authorization-code grant): consent URL, code exchange and refresh. */\nimport type { OAuthClient, OAuthTokens } from \"@storyshelf/core/adapter/oauth\";\nimport { httpJson } from \"@storyshelf/core/utils\";\n\n/** Operator-registered Figma OAuth app (Figma → Settings → OAuth apps). */\nexport interface FigmaOAuthOptions {\n  clientId: string;\n  clientSecret: string;\n}\n\nconst AUTHORIZE_URL = \"https://www.figma.com/oauth\";\nconst TOKEN_URL = \"https://api.figma.com/v1/oauth/token\";\nconst REFRESH_URL = \"https://api.figma.com/v1/oauth/refresh\";\n/** Read-only: file content (names, versions, renders). */\nconst SCOPE = \"file_content:read\";\n/** Figma issues 90-day access tokens; used when a response omits `expires_in`. */\nconst DEFAULT_EXPIRES_S = 90 * 24 * 60 * 60;\n\ninterface TokenResponse {\n  access_token: string;\n  refresh_token?: string;\n  expires_in?: number;\n}\n\n/** OAuth app credentials from `FIGMA_CLIENT_ID` / `FIGMA_CLIENT_SECRET`, or undefined when either is unset. */\nexport function figmaOAuthFromEnv(\n  env: Record<string, string | undefined> = process.env,\n): FigmaOAuthOptions | undefined {\n  const clientId = env[\"FIGMA_CLIENT_ID\"];\n  const clientSecret = env[\"FIGMA_CLIENT_SECRET\"];\n  return clientId && clientSecret ? { clientId, clientSecret } : undefined;\n}\n\n/** Figma's {@link OAuthClient} for one registered OAuth app. */\nexport function createFigmaOAuth(options: FigmaOAuthOptions): OAuthClient {\n  const basic = `Basic ${Buffer.from(`${options.clientId}:${options.clientSecret}`).toString(\"base64\")}`;\n  const post = async (\n    url: string,\n    form: Record<string, string>,\n    signal?: AbortSignal,\n  ): Promise<OAuthTokens> => {\n    const response = await httpJson<TokenResponse>(url, {\n      method: \"POST\",\n      headers: { Authorization: basic },\n      form,\n      retries: 1,\n      ...(signal ? { signal } : {}),\n    });\n    return toTokens(response);\n  };\n  return {\n    authorizeUrl: ({ state, redirectUri }) => {\n      const params = new URLSearchParams({\n        client_id: options.clientId,\n        redirect_uri: redirectUri,\n        scope: SCOPE,\n        state,\n        response_type: \"code\",\n      });\n      return `${AUTHORIZE_URL}?${params.toString()}`;\n    },\n    exchangeCode: async ({ code, redirectUri, signal }) =>\n      await post(\n        TOKEN_URL,\n        { redirect_uri: redirectUri, code, grant_type: \"authorization_code\" },\n        signal,\n      ),\n    refresh: async ({ refreshToken, signal }) =>\n      await post(REFRESH_URL, { refresh_token: refreshToken }, signal),\n  };\n}\n\nfunction toTokens(response: TokenResponse): OAuthTokens {\n  const seconds = response.expires_in ?? DEFAULT_EXPIRES_S;\n  return {\n    accessToken: response.access_token,\n    refreshToken: response.refresh_token ?? null,\n    expiresAt: new Date(Date.now() + seconds * 1000).toISOString(),\n  };\n}\n"],"mappings":";;;;;AAUA,MAAM,gBAAgB;AACtB,MAAM,YAAY;AAClB,MAAM,cAAc;;AAEpB,MAAM,QAAQ;;AAEd,MAAM,oBAAoB;;AAS1B,SAAgB,kBACd,MAA0C,QAAQ,KACnB;CAC/B,MAAM,WAAW,IAAI;CACrB,MAAM,eAAe,IAAI;CACzB,OAAO,YAAY,eAAe;EAAE;EAAU;CAAa,IAAI,KAAA;AACjE;;AAGA,SAAgB,iBAAiB,SAAyC;CACxE,MAAM,QAAQ,SAAS,OAAO,KAAK,GAAG,QAAQ,SAAS,GAAG,QAAQ,cAAc,CAAC,CAAC,SAAS,QAAQ;CACnG,MAAM,OAAO,OACX,KACA,MACA,WACyB;EAQzB,OAAO,SAAS,MAPO,SAAwB,KAAK;GAClD,QAAQ;GACR,SAAS,EAAE,eAAe,MAAM;GAChC;GACA,SAAS;GACT,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;EAC7B,CAAC,CACuB;CAC1B;CACA,OAAO;EACL,eAAe,EAAE,OAAO,kBAAkB;GACxC,MAAM,SAAS,IAAI,gBAAgB;IACjC,WAAW,QAAQ;IACnB,cAAc;IACd,OAAO;IACP;IACA,eAAe;GACjB,CAAC;GACD,OAAO,GAAG,cAAc,GAAG,OAAO,SAAS;EAC7C;EACA,cAAc,OAAO,EAAE,MAAM,aAAa,aACxC,MAAM,KACJ,WACA;GAAE,cAAc;GAAa;GAAM,YAAY;EAAqB,GACpE,MACF;EACF,SAAS,OAAO,EAAE,cAAc,aAC9B,MAAM,KAAK,aAAa,EAAE,eAAe,aAAa,GAAG,MAAM;CACnE;AACF;AAEA,SAAS,SAAS,UAAsC;CACtD,MAAM,UAAU,SAAS,cAAc;CACvC,OAAO;EACL,aAAa,SAAS;EACtB,cAAc,SAAS,iBAAiB;EACxC,WAAW,IAAI,KAAK,KAAK,IAAI,IAAI,UAAU,GAAI,CAAC,CAAC,YAAY;CAC/D;AACF"}

package/dist/url.d.mts

@@ -0,0 +1,13 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DesignRef } from "@storyshelf/core/adapter/design";
+//#region src/url.d.ts
+/**
+ * Parse a Figma file/design/board/proto/make URL, or null when it is not a Figma
+ * link. Embed (`/embed`), community and Figma Sites (`figma.site`) links are
+ * deliberately rejected, as are malformed `node-id` values.
+ */
+declare function parseFigmaUrl(raw: string): DesignRef | null;
+//#endregion
+export { parseFigmaUrl };
+//# sourceMappingURL=url.d.mts.map

package/dist/url.mjs

@@ -0,0 +1,43 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/url.ts
+const FIGMA_HOSTS = /* @__PURE__ */ new Set(["figma.com", "www.figma.com"]);
+const FILE_PATH = /^\/(?:file|design|proto|board|make)\/(?<key>[A-Za-z0-9]+)(?:\/|$)/u;
+/** `1:2` after normalizing; Figma node ids are `<number>:<number>`. */
+const NODE_ID = /^\d+:\d+$/u;
+/**
+* Parse a Figma file/design/board/proto/make URL, or null when it is not a Figma
+* link. Embed (`/embed`), community and Figma Sites (`figma.site`) links are
+* deliberately rejected, as are malformed `node-id` values.
+*/
+function parseFigmaUrl(raw) {
+	let url;
+	try {
+		url = new URL(raw.trim());
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "https:" || !FIGMA_HOSTS.has(url.hostname)) return null;
+	const fileKey = FILE_PATH.exec(url.pathname)?.groups?.["key"];
+	if (!fileKey) return null;
+	const node = url.searchParams.get("node-id")?.replaceAll("-", ":") ?? null;
+	if (node !== null && !NODE_ID.test(node)) return null;
+	return {
+		fileKey,
+		nodeId: node,
+		url: withoutCredentials(url)
+	};
+}
+/** The URL as stored and rendered into `href`s: no credentials, no fragment. */
+function withoutCredentials(url) {
+	const clean = new URL(url);
+	clean.username = "";
+	clean.password = "";
+	clean.hash = "";
+	return clean.toString();
+}
+//#endregion
+export { parseFigmaUrl };
+
+//# sourceMappingURL=url.mjs.map

package/dist/url.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.mjs","names":[],"sources":["../src/url.ts"],"sourcesContent":["/** Figma URL parsing: validates design links and extracts the file key and node id. */\nimport type { DesignRef } from \"@storyshelf/core/adapter/design\";\n\nconst FIGMA_HOSTS = new Set([\"figma.com\", \"www.figma.com\"]);\nconst FILE_PATH = /^\\/(?:file|design|proto|board|make)\\/(?<key>[A-Za-z0-9]+)(?:\\/|$)/u;\n/** `1:2` after normalizing; Figma node ids are `<number>:<number>`. */\nconst NODE_ID = /^\\d+:\\d+$/u;\n\n/**\n * Parse a Figma file/design/board/proto/make URL, or null when it is not a Figma\n * link. Embed (`/embed`), community and Figma Sites (`figma.site`) links are\n * deliberately rejected, as are malformed `node-id` values.\n */\nexport function parseFigmaUrl(raw: string): DesignRef | null {\n  let url: URL;\n  try {\n    url = new URL(raw.trim());\n  } catch {\n    return null;\n  }\n  if (url.protocol !== \"https:\" || !FIGMA_HOSTS.has(url.hostname)) return null;\n  const fileKey = FILE_PATH.exec(url.pathname)?.groups?.[\"key\"];\n  if (!fileKey) return null;\n  const node = url.searchParams.get(\"node-id\")?.replaceAll(\"-\", \":\") ?? null;\n  if (node !== null && !NODE_ID.test(node)) return null;\n  return { fileKey, nodeId: node, url: withoutCredentials(url) };\n}\n\n/** The URL as stored and rendered into `href`s: no credentials, no fragment. */\nfunction withoutCredentials(url: URL): string {\n  const clean = new URL(url);\n  clean.username = \"\";\n  clean.password = \"\";\n  clean.hash = \"\";\n  return clean.toString();\n}\n"],"mappings":";;;;AAGA,MAAM,8BAAc,IAAI,IAAI,CAAC,aAAa,eAAe,CAAC;AAC1D,MAAM,YAAY;;AAElB,MAAM,UAAU;;;;;;AAOhB,SAAgB,cAAc,KAA+B;CAC3D,IAAI;CACJ,IAAI;EACF,MAAM,IAAI,IAAI,IAAI,KAAK,CAAC;CAC1B,QAAQ;EACN,OAAO;CACT;CACA,IAAI,IAAI,aAAa,YAAY,CAAC,YAAY,IAAI,IAAI,QAAQ,GAAG,OAAO;CACxE,MAAM,UAAU,UAAU,KAAK,IAAI,QAAQ,CAAC,EAAE,SAAS;CACvD,IAAI,CAAC,SAAS,OAAO;CACrB,MAAM,OAAO,IAAI,aAAa,IAAI,SAAS,CAAC,EAAE,WAAW,KAAK,GAAG,KAAK;CACtE,IAAI,SAAS,QAAQ,CAAC,QAAQ,KAAK,IAAI,GAAG,OAAO;CACjD,OAAO;EAAE;EAAS,QAAQ;EAAM,KAAK,mBAAmB,GAAG;CAAE;AAC/D;;AAGA,SAAS,mBAAmB,KAAkB;CAC5C,MAAM,QAAQ,IAAI,IAAI,GAAG;CACzB,MAAM,WAAW;CACjB,MAAM,WAAW;CACjB,MAAM,OAAO;CACb,OAAO,MAAM,SAAS;AACxB"}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@storyshelf/design-figma",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "description": "Figma design-link provider for StoryShelf: link validation, file metadata and rendered previews.",
+  "keywords": [
+    "design",
+    "figma",
+    "self-hosted",
+    "storybook"
+  ],
+  "homepage": "https://github.com/GuptaSiddhant/StoryShelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/StoryShelf/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/StoryShelf.git",
+    "directory": "packages/design-figma"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "vitest run",
+    "prepublishOnly": "nub run build"
+  },
+  "dependencies": {
+    "@storyshelf/core": "0.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@vitest/coverage-v8": "^4.0.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "jsr": {
+    "runtimeCompat": {
+      "node": true,
+      "deno": true,
+      "browser": false,
+      "workerd": false,
+      "bun": true
+    }
+  }
+}