@harborclient/sdk 0.4.6 → 0.6.1

package/dist/variables/dynamic.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dynamic.test.d.ts.map

package/dist/variables/dynamic.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic.test.d.ts","sourceRoot":"","sources":["../../src/variables/dynamic.test.ts"],"names":[],"mappings":""}

package/dist/variables/dynamic.test.js

@@ -0,0 +1,60 @@
+import { describe, expect, it } from '@jest/globals';
+import { DYNAMIC_VARIABLE_CATEGORIES, DYNAMIC_VARIABLE_NAMES, DYNAMIC_VARIABLES, getDynamicVariableDescription, isDynamicVariable, resolveDynamicVariable } from './dynamic.js';
+describe('dynamicVariables', () => {
+    it('registers all Postman-style dynamic variable names with $ prefix', () => {
+        expect(DYNAMIC_VARIABLE_NAMES.length).toBeGreaterThan(100);
+        for (const name of DYNAMIC_VARIABLE_NAMES) {
+            expect(name.startsWith('$')).toBe(true);
+        }
+    });
+    it('generates a non-empty value for every registered dynamic variable', () => {
+        for (const name of DYNAMIC_VARIABLE_NAMES) {
+            const value = resolveDynamicVariable(name);
+            expect(value).toBeDefined();
+            expect(value.length).toBeGreaterThan(0);
+        }
+    });
+    it('isDynamicVariable and getDynamicVariableDescription reflect the registry', () => {
+        expect(isDynamicVariable('$guid')).toBe(true);
+        expect(isDynamicVariable('$randomFirstName')).toBe(true);
+        expect(isDynamicVariable('host')).toBe(false);
+        expect(isDynamicVariable('$unknownDynamic')).toBe(false);
+        expect(getDynamicVariableDescription('$guid')).toBe(DYNAMIC_VARIABLES.$guid.description);
+        expect(getDynamicVariableDescription('host')).toBeUndefined();
+    });
+    it('resolveDynamicVariable returns undefined for unknown keys', () => {
+        expect(resolveDynamicVariable('$notARealVariable')).toBeUndefined();
+    });
+    it('$guid and $randomUUID produce uuid-v4 shaped values', () => {
+        const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        expect(resolveDynamicVariable('$guid')).toMatch(uuidPattern);
+        expect(resolveDynamicVariable('$randomUUID')).toMatch(uuidPattern);
+    });
+    it('$timestamp returns a numeric unix seconds string', () => {
+        const value = resolveDynamicVariable('$timestamp');
+        expect(value).toMatch(/^\d+$/);
+        const seconds = Number(value);
+        expect(seconds).toBeGreaterThan(1_500_000_000);
+        expect(seconds).toBeLessThanOrEqual(Math.floor(Date.now() / 1000));
+    });
+    it('$isoTimestamp returns an ISO-8601 UTC string', () => {
+        const value = resolveDynamicVariable('$isoTimestamp');
+        expect(value).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/);
+        expect(() => new Date(value).toISOString()).not.toThrow();
+    });
+    it('generates fresh values on each resolve call for random variables', () => {
+        const first = resolveDynamicVariable('$randomInt');
+        const second = resolveDynamicVariable('$randomInt');
+        expect(first).toMatch(/^\d+$/);
+        expect(second).toMatch(/^\d+$/);
+    });
+    it('lists every dynamic variable exactly once across documentation categories', () => {
+        const categorized = DYNAMIC_VARIABLE_CATEGORIES.flatMap((category) => category.keys);
+        const unique = new Set(categorized);
+        expect(categorized.length).toBe(DYNAMIC_VARIABLE_NAMES.length);
+        expect(unique.size).toBe(DYNAMIC_VARIABLE_NAMES.length);
+        for (const name of DYNAMIC_VARIABLE_NAMES) {
+            expect(unique.has(name)).toBe(true);
+        }
+    });
+});

package/dist/variables/index.d.ts

@@ -0,0 +1,3 @@
+export { DYNAMIC_VARIABLES, DYNAMIC_VARIABLE_CATEGORIES, DYNAMIC_VARIABLE_NAMES, getDynamicVariableDescription, isDynamicVariable, resolveDynamicVariable, type DynamicVariableDefinition } from './dynamic.js';
+export { VARIABLE_NAME_CHARS, VARIABLE_TOKEN_PATTERN, resolveVariable, substituteVariables, tokenizeVariables, type VariableToken } from './tokens.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/variables/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/variables/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,2BAA2B,EAC3B,sBAAsB,EACtB,6BAA6B,EAC7B,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,yBAAyB,EAC/B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC"}

package/dist/variables/index.js

@@ -0,0 +1,2 @@
+export { DYNAMIC_VARIABLES, DYNAMIC_VARIABLE_CATEGORIES, DYNAMIC_VARIABLE_NAMES, getDynamicVariableDescription, isDynamicVariable, resolveDynamicVariable } from './dynamic.js';
+export { VARIABLE_NAME_CHARS, VARIABLE_TOKEN_PATTERN, resolveVariable, substituteVariables, tokenizeVariables } from './tokens.js';

package/dist/variables/tokens.d.ts

@@ -0,0 +1,44 @@
+import type { Variable } from '../types.js';
+/**
+ * A segment of text, optionally marking a {{variable}} token.
+ */
+export interface VariableToken {
+    text: string;
+    key?: string;
+}
+/**
+ * Allowed characters inside a `{{variable}}` token name (excluding braces).
+ * Includes `$` so Postman-style dynamic names such as `$randomUUID` are recognized.
+ */
+export declare const VARIABLE_NAME_CHARS = "\\w$.-";
+/**
+ * Global regex matching `{{variableName}}` placeholders in request text.
+ */
+export declare const VARIABLE_TOKEN_PATTERN: RegExp;
+/**
+ * Splits text into plain and {{variable}} segments.
+ *
+ * @param text - Text containing variable placeholders.
+ * @returns Ordered tokens for rendering or further processing.
+ */
+export declare function tokenizeVariables(text: string): VariableToken[];
+/**
+ * Resolves a single variable key against collection variables.
+ *
+ * @param key - Variable name from a {{key}} placeholder.
+ * @param variables - Collection-scoped variables.
+ * @returns Resolved value, or undefined when the key is not defined.
+ */
+export declare function resolveVariable(key: string, variables: Variable[]): string | undefined;
+/**
+ * Replaces {{key}} placeholders in text with collection variable values.
+ *
+ * Static collection/environment variables take precedence over dynamic variables.
+ * Unknown tokens are left unchanged.
+ *
+ * @param text - Text containing variable placeholders.
+ * @param variables - Collection-scoped variables.
+ * @returns Text with known variables substituted; unknown tokens are left unchanged.
+ */
+export declare function substituteVariables(text: string, variables: Variable[]): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/variables/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/variables/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,WAAW,CAAC;AAE5C;;GAEG;AACH,eAAO,MAAM,sBAAsB,QAGlC,CAAC;AAgBF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAmB/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,GAAG,SAAS,CAEtF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,CAY/E"}

package/dist/variables/tokens.js

@@ -0,0 +1,76 @@
+import { resolveDynamicVariable } from './dynamic.js';
+/**
+ * Allowed characters inside a `{{variable}}` token name (excluding braces).
+ * Includes `$` so Postman-style dynamic names such as `$randomUUID` are recognized.
+ */
+export const VARIABLE_NAME_CHARS = '\\w$.-';
+/**
+ * Global regex matching `{{variableName}}` placeholders in request text.
+ */
+export const VARIABLE_TOKEN_PATTERN = new RegExp(`\\{\\{\\s*([${VARIABLE_NAME_CHARS}]+)\\s*\\}\\}`, 'g');
+/**
+ * Builds a lookup map from collection variables.
+ *
+ * @param variables - Collection-scoped variables.
+ * @returns Map of trimmed keys to resolved values.
+ */
+function variableLookup(variables) {
+    return new Map(variables
+        .filter((v) => v.key.trim())
+        .map((v) => [v.key.trim(), v.value !== '' ? v.value : v.defaultValue]));
+}
+/**
+ * Splits text into plain and {{variable}} segments.
+ *
+ * @param text - Text containing variable placeholders.
+ * @returns Ordered tokens for rendering or further processing.
+ */
+export function tokenizeVariables(text) {
+    const tokens = [];
+    const pattern = new RegExp(VARIABLE_TOKEN_PATTERN.source, 'g');
+    let lastIndex = 0;
+    for (const match of text.matchAll(pattern)) {
+        const index = match.index ?? 0;
+        if (index > lastIndex) {
+            tokens.push({ text: text.slice(lastIndex, index) });
+        }
+        tokens.push({ text: match[0], key: match[1] });
+        lastIndex = index + match[0].length;
+    }
+    if (lastIndex < text.length) {
+        tokens.push({ text: text.slice(lastIndex) });
+    }
+    return tokens;
+}
+/**
+ * Resolves a single variable key against collection variables.
+ *
+ * @param key - Variable name from a {{key}} placeholder.
+ * @param variables - Collection-scoped variables.
+ * @returns Resolved value, or undefined when the key is not defined.
+ */
+export function resolveVariable(key, variables) {
+    return variableLookup(variables).get(key);
+}
+/**
+ * Replaces {{key}} placeholders in text with collection variable values.
+ *
+ * Static collection/environment variables take precedence over dynamic variables.
+ * Unknown tokens are left unchanged.
+ *
+ * @param text - Text containing variable placeholders.
+ * @param variables - Collection-scoped variables.
+ * @returns Text with known variables substituted; unknown tokens are left unchanged.
+ */
+export function substituteVariables(text, variables) {
+    const lookup = variableLookup(variables);
+    const pattern = new RegExp(VARIABLE_TOKEN_PATTERN.source, 'g');
+    return text.replace(pattern, (match, key) => {
+        const value = lookup.get(key);
+        if (value !== undefined) {
+            return value;
+        }
+        const dynamic = resolveDynamicVariable(key);
+        return dynamic !== undefined ? dynamic : match;
+    });
+}

package/dist/variables/tokens.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tokens.test.d.ts.map

package/dist/variables/tokens.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.test.d.ts","sourceRoot":"","sources":["../../src/variables/tokens.test.ts"],"names":[],"mappings":""}

package/dist/variables/tokens.test.js

@@ -0,0 +1,115 @@
+import { describe, expect, it } from '@jest/globals';
+import { resolveVariable, substituteVariables, tokenizeVariables } from './tokens.js';
+/**
+ * Builds a test variable row.
+ *
+ * @param key - Variable name.
+ * @param value - Current value.
+ * @param defaultValue - Fallback when value is empty.
+ * @param share - Whether the variable is shared on export.
+ */
+const variable = (key, value, defaultValue = '', share = false) => ({
+    key,
+    value,
+    defaultValue,
+    share
+});
+describe('substituteVariables', () => {
+    it('replaces known variable tokens', () => {
+        const result = substituteVariables('https://{{host}}/api/{{version}}', [
+            variable('host', 'api.example.com'),
+            variable('version', 'v1')
+        ]);
+        expect(result).toBe('https://api.example.com/api/v1');
+    });
+    it('leaves unknown tokens unchanged', () => {
+        const result = substituteVariables('https://{{host}}/{{missing}}', [
+            variable('host', 'api.example.com')
+        ]);
+        expect(result).toBe('https://api.example.com/{{missing}}');
+    });
+    it('substitutes {{ host }} when token key has surrounding whitespace', () => {
+        const result = substituteVariables('https://{{ host }}/users', [
+            variable('host', 'api.example.com')
+        ]);
+        expect(result).toBe('https://api.example.com/users');
+    });
+    it('trims variable keys when building the lookup', () => {
+        const result = substituteVariables('https://{{host}}', [
+            variable('  host  ', 'api.example.com')
+        ]);
+        expect(result).toBe('https://api.example.com');
+    });
+    it('ignores blank-key variables', () => {
+        const result = substituteVariables('https://{{host}}', [
+            variable('   ', 'ignored.example.com'),
+            variable('host', 'api.example.com')
+        ]);
+        expect(result).toBe('https://api.example.com');
+    });
+    it('falls back to defaultValue when value is empty', () => {
+        const result = substituteVariables('https://{{host}}/api', [variable('host', '', 'localhost')]);
+        expect(result).toBe('https://localhost/api');
+    });
+    it('prefers value over defaultValue when both are set', () => {
+        const result = substituteVariables('https://{{host}}/api', [
+            variable('host', 'api.example.com', 'localhost')
+        ]);
+        expect(result).toBe('https://api.example.com/api');
+    });
+    it('substitutes variables in collection header values', () => {
+        const result = substituteVariables('Bearer {{token}}', [variable('token', 'abc123')]);
+        expect(result).toBe('Bearer abc123');
+    });
+    it('resolves dynamic variables when no static variable is defined', () => {
+        const result = substituteVariables('id={{ $guid }}', []);
+        expect(result).not.toContain('{{');
+        expect(result).toMatch(/^id=[0-9a-f-]{36}$/i);
+    });
+    it('prefers static variables over dynamic variables with the same key', () => {
+        const result = substituteVariables('{{$randomInt}}', [variable('$randomInt', '42')]);
+        expect(result).toBe('42');
+    });
+    it('leaves unknown dynamic-style tokens unchanged', () => {
+        const result = substituteVariables('{{$notRegistered}}', []);
+        expect(result).toBe('{{$notRegistered}}');
+    });
+});
+describe('tokenizeVariables', () => {
+    it('returns a single plain-text token when no variables are present', () => {
+        expect(tokenizeVariables('https://api.example.com')).toEqual([
+            { text: 'https://api.example.com' }
+        ]);
+    });
+    it('splits text around variable tokens', () => {
+        expect(tokenizeVariables('https://{{host}}/api/{{version}}')).toEqual([
+            { text: 'https://' },
+            { text: '{{host}}', key: 'host' },
+            { text: '/api/' },
+            { text: '{{version}}', key: 'version' }
+        ]);
+    });
+    it('tokenizeVariables extracts host key from {{ host }} token', () => {
+        expect(tokenizeVariables('https://{{ host }}/users')).toEqual([
+            { text: 'https://' },
+            { text: '{{ host }}', key: 'host' },
+            { text: '/users' }
+        ]);
+    });
+    it('tokenizeVariables recognizes dynamic variable keys with $ prefix', () => {
+        expect(tokenizeVariables('{{$randomUUID}}')).toEqual([
+            { text: '{{$randomUUID}}', key: '$randomUUID' }
+        ]);
+    });
+});
+describe('resolveVariable', () => {
+    it('returns the resolved value for a known key', () => {
+        expect(resolveVariable('host', [variable('host', 'api.example.com')])).toBe('api.example.com');
+    });
+    it('falls back to defaultValue when value is empty', () => {
+        expect(resolveVariable('host', [variable('host', '', 'localhost')])).toBe('localhost');
+    });
+    it('returns undefined for unknown keys', () => {
+        expect(resolveVariable('missing', [variable('host', 'api.example.com')])).toBeUndefined();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harborclient/sdk",
-  "version": "0.4.6",
+  "version": "0.6.1",
   "description": "TypeScript SDK for HarborClient plugin development.",
   "keywords": [
     "harborclient",
@@ -22,54 +22,89 @@
     "email": "contact@harborclient.com"
   },
   "type": "module",
+  "sideEffects": false,
   "types": "./dist/client.d.ts",
   "exports": {
     ".": {
       "types": "./dist/client.d.ts",
-      "import": "./dist/runtime/index.js"
+      "import": "./dist/runtime/index.js",
+      "require": "./dist/runtime/index.js",
+      "default": "./dist/runtime/index.js"
     },
     "./jsx-runtime": {
       "types": "./dist/runtime/jsx-runtime.d.ts",
-      "import": "./dist/runtime/jsx-runtime.js"
+      "import": "./dist/runtime/jsx-runtime.js",
+      "require": "./dist/runtime/jsx-runtime.js",
+      "default": "./dist/runtime/jsx-runtime.js"
     },
     "./jsx-dev-runtime": {
       "types": "./dist/runtime/jsx-dev-runtime.d.ts",
-      "import": "./dist/runtime/jsx-dev-runtime.js"
+      "import": "./dist/runtime/jsx-dev-runtime.js",
+      "require": "./dist/runtime/jsx-dev-runtime.js",
+      "default": "./dist/runtime/jsx-dev-runtime.js"
     },
     "./react": {
       "types": "./dist/runtime/react.d.ts",
-      "import": "./dist/runtime/react.js"
+      "import": "./dist/runtime/react.js",
+      "require": "./dist/runtime/react.js",
+      "default": "./dist/runtime/react.js"
     },
     "./main": {
       "types": "./dist/main.d.ts"
     },
     "./http": {
       "types": "./dist/http/index.d.ts",
-      "import": "./dist/http/index.js"
+      "import": "./dist/http/index.js",
+      "require": "./dist/http/index.js",
+      "default": "./dist/http/index.js"
+    },
+    "./variables": {
+      "types": "./dist/variables/index.d.ts",
+      "import": "./dist/variables/index.js",
+      "require": "./dist/variables/index.js",
+      "default": "./dist/variables/index.js"
     },
     "./ui": {
       "types": "./dist/ui/index.d.ts",
-      "import": "./dist/ui/index.js"
+      "import": "./dist/ui/index.js",
+      "require": "./dist/ui/index.js",
+      "default": "./dist/ui/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js",
+      "require": "./dist/components/index.js",
+      "default": "./dist/components/index.js"
     },
     "./storage": {
       "types": "./dist/storage/index.d.ts",
-      "import": "./dist/storage/index.js"
+      "import": "./dist/storage/index.js",
+      "require": "./dist/storage/index.js",
+      "default": "./dist/storage/index.js"
     },
     "./clipboard": {
       "types": "./dist/clipboard.d.ts",
-      "import": "./dist/clipboard.js"
+      "import": "./dist/clipboard.js",
+      "require": "./dist/clipboard.js",
+      "default": "./dist/clipboard.js"
     },
     "./runtime-utils": {
       "types": "./dist/runtime-utils.d.ts",
-      "import": "./dist/runtime-utils.js"
+      "import": "./dist/runtime-utils.js",
+      "require": "./dist/runtime-utils.js",
+      "default": "./dist/runtime-utils.js"
     },
     "./store": {
       "types": "./dist/runtime/store.d.ts",
-      "import": "./dist/runtime/store.js"
+      "import": "./dist/runtime/store.js",
+      "require": "./dist/runtime/store.js",
+      "default": "./dist/runtime/store.js"
     },
     "./signing": {
       "types": "./dist/signing/index.d.ts",
-      "import": "./dist/signing/index.js"
+      "import": "./dist/signing/index.js",
+      "require": "./dist/signing/index.js",
+      "default": "./dist/signing/index.js"
     }
   },
   "bin": {
@@ -85,10 +120,29 @@
   "peerDependencies": {
     "react": ">=18"
   },
+  "dependencies": {
+    "@codemirror/autocomplete": "^6.20.3",
+    "@codemirror/lang-javascript": "^6.2.4",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/legacy-modes": "^6.5.3",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.43.1",
+    "@faker-js/faker": "^10.5.0",
+    "@fortawesome/fontawesome-svg-core": "^7.2.0",
+    "@fortawesome/free-solid-svg-icons": "^7.2.0",
+    "@fortawesome/react-fontawesome": "^3.3.1",
+    "@lezer/highlight": "^1.2.3",
+    "@uiw/codemirror-themes-all": "^4.25.10",
+    "@uiw/react-codemirror": "^4.25.10"
+  },
   "devDependencies": {
     "@braintree/sanitize-url": "^7.1.2",
     "@eslint/js": "^10.0.1",
     "@jest/globals": "^30.4.1",
+    "@storybook/addon-docs": "^10.4.6",
+    "@storybook/react-vite": "^10.4.6",
+    "@tailwindcss/vite": "^4.3.1",
     "@types/node": "^26.0.1",
     "@types/react": "^19.1.2",
     "concurrently": "^8.2.2",
@@ -101,14 +155,19 @@
     "jest": "^30.4.2",
     "mermaid": "^11.15.0",
     "prettier": "^3.8.4",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "storybook": "^10.4.6",
+    "tailwindcss": "^4.3.1",
     "ts-jest": "^29.4.11",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.62.0",
+    "vite": "^8.1.0",
     "vitepress": "^1.6.4",
     "vitepress-plugin-mermaid": "^2.0.17"
   },
   "scripts": {
-    "build": "tsc && node scripts/copy-runtime.mjs",
+    "build": "tsc -p tsconfig.build.json && node scripts/copy-runtime.mjs",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint --cache .",
@@ -120,7 +179,9 @@
     "release:patch": "gh workflow run Release --ref main -f release_type=patch",
     "release:minor": "gh workflow run Release --ref main -f release_type=minor",
     "release:major": "gh workflow run Release --ref main -f release_type=major",
-    "docs:build": "pnpm docs:build:nav && vitepress build docs",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build -o docs/.vitepress/static/storybook",
+    "docs:build": "pnpm docs:build:nav && pnpm build-storybook && vitepress build docs",
     "docs:build:nav": "node scripts/build-docs-nav.mjs && node scripts/assert-docs-slugs.mjs",
     "docs:preview": "pnpm docs:build && vitepress preview docs",
     "docs:serve": "pnpm docs:build:nav && concurrently --kill-others --prefixColors=auto -n nav,vp \"node scripts/watch-docs-nav.mjs\" \"vitepress dev docs\"",