@scaleflex/asset-picker 0.2.0 → 0.2.1

package/.claude/settings.local.json

@@ -0,0 +1,49 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls:*)",
+      "Bash(grep:*)",
+      "Bash(npm install:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vite:*)",
+      "WebFetch(domain:localhost)",
+      "Bash(curl:*)",
+      "Bash(node:*)",
+      "WebSearch",
+      "Bash(npm run:*)",
+      "Bash(wc:*)",
+      "WebFetch(domain:unpkg.com)",
+      "Bash(git:*)",
+      "Bash(find /Users/dmitrystremous/scaleflex -maxdepth 3 -type d -name \"*admin*\" 2>/dev/null | grep -i filerobot)",
+      "Bash(gh run:*)",
+      "Bash(gh workflow:*)",
+      "Bash(find:*)",
+      "Bash(npx playwright:*)",
+      "Bash(npm ls:*)",
+      "Read(//Users/dmitrystremous/**)",
+      "Bash(npx:*)",
+      "Bash(rm:*)",
+      "Bash(tail:*)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(gh api:*)",
+      "WebFetch(domain:www.scaleflex.com)",
+      "WebFetch(domain:scaleflex.github.io)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:portals.scaleflex.com)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Read(//Users/dmitrystremous/scaleflex/asset-picker/**)",
+      "Bash(done)",
+      "Bash(cd:*)",
+      "Bash(chmod:*)",
+      "Bash(./scripts/publish-github.sh \"v0.1.0 — initial release\" 2>&1)",
+      "Bash(npm whoami:*)",
+      "Bash(npm publish:*)",
+      "Bash(gh repo:*)",
+      "Bash(./scripts/publish-github.sh \"Update README with demo and docs links\" 2>&1)",
+      "Bash(lsof:*)",
+      "Bash(kill:*)",
+      "Bash(npm view:*)"
+    ]
+  }
+}

package/.claude/skills/integrate-asset-picker/SKILL.md

@@ -0,0 +1,391 @@
+---
+name: integrate-asset-picker
+description: Integrate @scaleflex/asset-picker into any project — install, configure auth,
+  wire events, theme, and add filters. Works with vanilla JS, React, Vue, Angular, Svelte.
+user_invocable: true
+metadata:
+  category: integration
+  tags:
+  - scaleflex
+  - dam
+  - asset-picker
+  - web-component
+  status: ready
+  version: 1
+---
+
+# Scaleflex Asset Picker Integration Skill
+
+## When to Use
+
+- User says "add asset picker", "integrate asset picker", "DAM picker", "file picker from Scaleflex"
+- User wants to let users browse/select assets from Scaleflex VXP DAM
+- User asks how to use `@scaleflex/asset-picker` in their project
+
+## Step 1 — Detect the Target Framework
+
+Read the project's `package.json` to determine:
+- **React** (18+): use the React wrapper (`@scaleflex/asset-picker/react`)
+- **Vue / Angular / Svelte / vanilla JS**: use the Web Component (`@scaleflex/asset-picker/define`)
+
+## Step 2 — Install
+
+```bash
+npm install @scaleflex/asset-picker
+```
+
+`lit` is bundled — no extra peer deps for vanilla JS / Vue / Angular / Svelte.
+For React, `react` and `react-dom` (v18+) must already be installed (they're optional peer deps).
+
+### Optional: Uploader integration
+
+If the user wants upload functionality inside the picker:
+
+```bash
+npm install @scaleflex/uploader
+```
+
+## Step 3 — Add the Picker
+
+### Vanilla JS / Web Component
+
+```js
+import '@scaleflex/asset-picker/define';
+
+const picker = document.querySelector('sfx-asset-picker')
+  || document.createElement('sfx-asset-picker');
+document.body.appendChild(picker);
+
+picker.config = {
+  auth: {
+    mode: 'securityTemplate',
+    securityTemplateKey: 'YOUR_SECURITY_TEMPLATE_KEY',
+    projectToken: 'YOUR_PROJECT_TOKEN',
+  },
+};
+
+picker.addEventListener('ap-select', (e) => {
+  const assets = e.detail.assets;
+  console.log('Selected:', assets);
+});
+
+picker.addEventListener('ap-cancel', () => {
+  console.log('Cancelled');
+});
+
+picker.open();
+```
+
+### React
+
+```tsx
+import { useRef, useState } from 'react';
+import { AssetPicker, type AssetPickerRef } from '@scaleflex/asset-picker/react';
+import type { Asset } from '@scaleflex/asset-picker';
+
+function MyComponent() {
+  const pickerRef = useRef<AssetPickerRef>(null);
+
+  const config = {
+    auth: {
+      mode: 'securityTemplate' as const,
+      securityTemplateKey: 'YOUR_SECURITY_TEMPLATE_KEY',
+      projectToken: 'YOUR_PROJECT_TOKEN',
+    },
+  };
+
+  const handleSelect = (assets: Asset[]) => {
+    console.log('Selected:', assets);
+  };
+
+  return (
+    <>
+      <button onClick={() => pickerRef.current?.open()}>Pick assets</button>
+      <AssetPicker
+        ref={pickerRef}
+        config={config}
+        onSelect={handleSelect}
+        onCancel={() => console.log('Cancelled')}
+      />
+    </>
+  );
+}
+```
+
+**React controlled mode** (open state managed by parent):
+
+```tsx
+const [isOpen, setIsOpen] = useState(false);
+
+<AssetPicker
+  config={config}
+  open={isOpen}
+  onSelect={(assets) => { handleSelect(assets); setIsOpen(false); }}
+  onCancel={() => setIsOpen(false)}
+/>
+```
+
+### Vue
+
+```vue
+<template>
+  <sfx-asset-picker ref="picker"></sfx-asset-picker>
+  <button @click="openPicker">Pick assets</button>
+</template>
+
+<script setup>
+import '@scaleflex/asset-picker/define';
+import { ref, onMounted } from 'vue';
+
+const picker = ref(null);
+
+onMounted(() => {
+  const el = picker.value;
+  el.config = {
+    auth: {
+      mode: 'securityTemplate',
+      securityTemplateKey: 'YOUR_SECURITY_TEMPLATE_KEY',
+      projectToken: 'YOUR_PROJECT_TOKEN',
+    },
+  };
+
+  el.addEventListener('ap-select', (e) => {
+    console.log('Selected:', e.detail.assets);
+  });
+});
+
+function openPicker() {
+  picker.value?.open();
+}
+</script>
+```
+
+## Step 4 — Authentication
+
+Ask the user which auth mode they need:
+
+### Security template (external / public apps)
+
+The picker auto-exchanges the key for a SASS key on init. Safer for client-side code.
+
+```ts
+auth: {
+  mode: 'securityTemplate',
+  securityTemplateKey: string,  // From Scaleflex dashboard
+  projectToken: string,
+}
+```
+
+### SASS key (internal / Scaleflex apps)
+
+Use when the application already has a SASS key — e.g. inside the Scaleflex Hub where the host app manages SASS key generation and renewal.
+
+```ts
+auth: {
+  mode: 'sassKey',
+  sassKey: string,         // X-Filerobot-Key
+  projectToken: string,
+}
+```
+
+## Step 5 — Configure (Optional)
+
+All options beyond `auth` are optional. Add only what the user needs:
+
+```ts
+picker.config = {
+  auth: { /* ... */ },
+
+  // Display
+  displayMode: 'modal',              // 'modal' (default) or 'inline'
+  defaultViewMode: 'grid',           // 'grid' (default) or 'list'
+  brandColor: '#6366f1',             // Hex color for accent theme
+
+  // Selection
+  multiSelect: true,                 // default: true
+  maxSelections: 5,                  // limit selections
+
+  // Navigation
+  rootFolderPath: '/marketing/',     // start in a specific folder
+  tabs: ['assets', 'folders'],       // default: both. Use ['assets'] to hide folders tab
+  rememberLastFolder: true,          // persist last folder in localStorage
+  rememberLastView: true,            // persist grid/list preference
+
+  // Sorting
+  defaultSortBy: 'created_at',      // 'name' | 'created_at' | 'modified_at' | 'size' | 'type' | etc.
+  defaultSortDirection: 'desc',     // 'asc' | 'desc'
+
+  // Filters
+  enabledFilters: ['type', 'tags', 'date'],  // restrict visible filters
+  defaultFilters: {                           // pre-applied, user can remove
+    type: { type: 'string', values: ['image'] },
+  },
+  forcedFilters: {                            // locked, user cannot remove
+    tags: { type: 'string', values: ['approved'] },
+  },
+
+  // Metadata
+  showMetadata: true,                // show metadata in preview panel
+
+  // Uploader (requires @scaleflex/uploader installed)
+  uploader: {
+    autoProceed: false,
+    restrictions: {
+      maxFileSize: 10_000_000,       // 10 MB
+      allowedFileTypes: ['image/*', 'video/*'],
+    },
+  },
+};
+```
+
+## Events Reference
+
+All events bubble and cross Shadow DOM (`composed: true`):
+
+| Event | Detail | When |
+|---|---|---|
+| `ap-select` | `{ assets: Asset[] }` | User confirms selection |
+| `ap-cancel` | `{ reason: 'backdrop' \| 'escape' \| 'button' \| 'close-button' }` | Picker closed without selecting |
+| `ap-open` | `{ timestamp: number }` | Picker opened successfully |
+| `ap-error` | `{ error: Error, context: string }` | Initialization or runtime error |
+
+## Public Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `open()` | `Promise<void>` | Open the picker, init API if needed |
+| `close()` | `void` | Close and clear selection |
+
+## Asset Object Shape
+
+The `Asset` returned in `ap-select`:
+
+```ts
+interface Asset {
+  uuid: string;
+  name: string;
+  extension: string;
+  type: string;              // 'image', 'video', 'audio', 'document', ...
+  mime?: string;
+  size: { bytes: number; pretty: string };
+  url?: {
+    public: string;          // Public URL
+    cdn: string;             // CDN-optimised URL
+    path: string;            // Relative path
+    permalink?: string;
+  };
+  created_at: string;
+  modified_at: string;
+  tags: Record<string, any>;
+  labels: string[];
+  meta: { title?: string; description?: string; alt?: string; [key: string]: unknown };
+  info: {
+    img_w?: number; img_h?: number;
+    duration?: number;
+    video_w?: number; video_h?: number;
+    thumbnail?: string;
+    main_colors_hex?: string[];
+    dominant_color_hex?: string;
+    [key: string]: unknown;
+  };
+  folder?: { uuid: string; name: string };
+  owner?: { uuid: string; name: string; email: string };
+}
+```
+
+## Theming
+
+### Quick: brandColor config
+
+```ts
+picker.config = { auth: { /* ... */ }, brandColor: '#6366f1' };
+```
+
+### Advanced: CSS custom properties
+
+Override on the element or any ancestor. All use `--ap-` prefix:
+
+```css
+sfx-asset-picker {
+  --ap-primary: #6366f1;
+  --ap-primary-foreground: #fff;
+  --ap-background: #ffffff;
+  --ap-foreground: #09090b;
+  --ap-border: #e4e4e7;
+  --ap-muted: #f4f4f5;
+  --ap-muted-foreground: #71717a;
+  --ap-radius: 8px;
+  --ap-font-family: 'Inter', system-ui, sans-serif;
+  --ap-modal-max-width: 1400px;
+  --ap-modal-max-height: 90vh;
+}
+```
+
+## Filter Data Structures
+
+For `defaultFilters` and `forcedFilters`:
+
+```ts
+// String filter (type, mimetype, tags, labels, size, etc.)
+{ type: 'string', values: ['image'], operator?: ':', logic?: 'OR' }
+
+// Date filter
+{
+  type: 'date',
+  field: 'created' | 'updated',
+  kind: 'preset' | 'after' | 'before' | 'between' | 'specific' | null,
+  preset: 'today' | 'last_week' | 'last_month' | 'last_year' | null,
+  from: string | null,  // ISO date
+  to: string | null,    // ISO date
+}
+```
+
+**Filter keys:** `type`, `mimetype`, `date`, `size`, `tags`, `labels`, `color`, `image`, `approval`, `metadata`, `product_ref`, `asset_expiration`, `folders`, `resolution`, `orientation`, `faces`, `products`
+
+## Common Patterns
+
+### Single image picker
+
+```ts
+config = {
+  auth: { /* ... */ },
+  multiSelect: false,
+  forcedFilters: { type: { type: 'string', values: ['image'] } },
+  tabs: ['assets'],
+};
+```
+
+### Inline mode (embedded in page, not modal)
+
+```ts
+config = {
+  auth: { /* ... */ },
+  displayMode: 'inline',
+};
+```
+
+Style the container height:
+```css
+sfx-asset-picker { --ap-inline-height: 500px; }
+```
+
+### With uploader drop zone
+
+```ts
+config = {
+  auth: { /* ... */ },
+  uploader: {
+    autoProceed: true,
+    restrictions: { maxFileSize: 50_000_000 },
+  },
+};
+```
+
+Requires `@scaleflex/uploader` installed as peer dependency.
+
+## Troubleshooting
+
+- **"customElements is not defined"** — SSR environment. The React wrapper handles this automatically. For vanilla JS, guard the import: `if (typeof customElements !== 'undefined') import('@scaleflex/asset-picker/define');`
+- **Styles not showing** — The component uses Shadow DOM; external CSS won't penetrate. Use `--ap-*` CSS custom properties for theming.
+- **Auth errors** — Check that the security template key or SASS key is valid and the project token matches.
+- **`open()` does nothing** — `config` must be set before calling `open()`. Ensure `auth` is provided.

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="https://www.scaleflex.com">
-    <img src="https://scaleflex.cloudimg.io/v7/plugins/js-cloudimage-360-view/logo_scaleflex_on_white_bg.jpg?vh=91b12d&w=700" alt="Scaleflex" width="350">
+    <img src="https://scaleflex.cloudimg.io/v7/plugins/scaleflex/logo.png?vh=b0a502&radius=25&w=700" alt="Scaleflex" width="350">
   </a>
 </p>
 
@@ -54,6 +54,7 @@
   - [Asset](#asset)
   - [Folder](#folder)
 - [Browser Support](#browser-support)
+- [Claude Code Integration](#claude-code-integration)
 - [License](#license)
 
 ---
@@ -68,7 +69,7 @@ The npm package contains **only pre-built, minified production files** (`dist/`)
 
 - **Framework-agnostic** — standard `<sfx-asset-picker>` custom element, works in any stack
 - **First-class React wrapper** — `forwardRef` component with controlled `open` prop and imperative ref
-- **Two auth modes** — session tokens or security templates
+- **Two auth modes** — security templates or direct SASS key
 - **Grid & list views** — switchable with persistent user preference
 - **Full-text search** — real-time search across your DAM
 - **14+ filter types** — type, date, size, tags, labels, color, approval status, metadata, and more
@@ -88,7 +89,7 @@ The npm package contains **only pre-built, minified production files** (`dist/`)
 ## Requirements
 
 - A [Scaleflex](https://www.scaleflex.com) VXP DAM account with a project token
-- Either **session credentials** or a **security template key** for authentication
+- Either a **security template key** or a **SASS key** for authentication
 - Modern browser with Custom Elements v1 support (see [Browser Support](#browser-support))
 
 ## Installation
@@ -198,7 +199,7 @@ The picker supports two authentication modes:
 
 #### Security template (external / public apps)
 
-Use for client-side integrations where you don't want to expose session tokens. The picker automatically exchanges the key for a SASS key on init.
+Use for client-side integrations. The picker automatically exchanges the security template key for a SASS key on init.
 
 ```ts
 {
@@ -210,17 +211,16 @@ Use for client-side integrations where you don't want to expose session tokens.
 }
 ```
 
-#### Session (internal / Scaleflex apps)
+#### SASS key (internal / Scaleflex apps)
 
-Use when your backend already manages Scaleflex sessions.
+Use when your application already has a SASS key — e.g. inside the Scaleflex Hub where the host app manages SASS key generation and renewal.
 
 ```ts
 {
   auth: {
-    mode: 'session',
-    sessionToken: string,   // X-Session-Token
-    companyToken: string,    // X-Company-Token
-    projectToken: string,    // X-Project-Token
+    mode: 'sassKey',
+    sassKey: string,         // X-Filerobot-Key
+    projectToken: string,
   }
 }
 ```
@@ -583,8 +583,8 @@ All types are exported from the main entry point:
 import type {
   AssetPickerConfig,
   AuthConfig,
-  SessionAuth,
   SecurityTemplateAuth,
+  SassKeyAuth,
   Asset,
   Folder,
   FilterKey,
@@ -691,6 +691,38 @@ Requires native support for Custom Elements v1, Shadow DOM, and ES2020+. Interne
 
 ---
 
+## Claude Code Integration
+
+If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), this package ships with a ready-made skill that helps Claude add the asset picker to your project — detecting your framework, wiring auth, events, theming, and filters automatically.
+
+### Option 1: Project-level (recommended)
+
+Copy the skill into your project so every team member who uses Claude Code gets it:
+
+```bash
+mkdir -p .claude/skills/integrate-asset-picker
+cp node_modules/@scaleflex/asset-picker/.claude/skills/integrate-asset-picker/SKILL.md \
+   .claude/skills/integrate-asset-picker/SKILL.md
+```
+
+Commit the `.claude/skills/` directory to version control. The skill is now available to everyone on the team.
+
+### Option 2: Global (personal)
+
+Install it once for all your projects:
+
+```bash
+mkdir -p ~/.claude/skills/integrate-asset-picker
+cp node_modules/@scaleflex/asset-picker/.claude/skills/integrate-asset-picker/SKILL.md \
+   ~/.claude/skills/integrate-asset-picker/SKILL.md
+```
+
+### Usage
+
+Type `/integrate-asset-picker` in Claude Code and it will walk you through the full integration — install, config, events, and theming — tailored to your stack (React, Vue, vanilla JS, etc.).
+
+---
+
 ## License
 
 **PROPRIETARY** &mdash; All Rights Reserved.

package/dist/{asset-picker-CSsp_Huy.js → asset-picker-CCQPEvDB.js}

@@ -259,7 +259,7 @@ class Is {
   constructor(e, s) {
     this.auth = e;
     const i = e.projectToken;
-    this.baseUrl = s || `https://api.filerobot.com/${i}/v5`;
+    this.baseUrl = s || `https://api.filerobot.com/${i}/v5`, e.mode === "sassKey" && (this.sassKey = e.sassKey);
   }
   setSassKey(e) {
     this.sassKey = e;
@@ -268,19 +268,16 @@ class Is {
     if (this.auth.mode === "securityTemplate")
       return this.auth.securityTemplateKey;
   }
+  _applyAuthHeaders(e) {
+    this.sassKey ? e["X-Filerobot-Key"] = this.sassKey : this.auth.mode === "securityTemplate" && (e["X-Filerobot-Key"] = this.auth.securityTemplateKey);
+  }
   async request(e, s) {
     const i = new URL(`${this.baseUrl}${e}`);
     s && Object.entries(s).forEach(([l, c]) => {
       c != null && (Array.isArray(c) ? i.searchParams.set(l, c.join(",")) : i.searchParams.set(l, String(c)));
     });
     const a = {};
-    if (this.auth.mode === "session") {
-      const l = this.auth;
-      a["X-Session-Token"] = l.sessionToken, a["X-Company-Token"] = l.companyToken, a["X-Project-Token"] = l.projectToken;
-    } else {
-      const l = this.auth;
-      this.sassKey ? a["X-Filerobot-Key"] = this.sassKey : a["X-Filerobot-Key"] = l.securityTemplateKey;
-    }
+    this._applyAuthHeaders(a);
     const r = new AbortController(), o = setTimeout(() => r.abort(), 3e4);
     try {
       const l = await fetch(i.toString(), { headers: a, signal: r.signal });
@@ -305,13 +302,7 @@ class Is {
     const i = new URL(`${this.baseUrl}${e}`), a = {
       "Content-Type": "application/json"
     };
-    if (this.auth.mode === "session") {
-      const l = this.auth;
-      a["X-Session-Token"] = l.sessionToken, a["X-Company-Token"] = l.companyToken, a["X-Project-Token"] = l.projectToken;
-    } else {
-      const l = this.auth;
-      this.sassKey ? a["X-Filerobot-Key"] = this.sassKey : a["X-Filerobot-Key"] = l.securityTemplateKey;
-    }
+    this._applyAuthHeaders(a);
     const r = new AbortController(), o = setTimeout(() => r.abort(), 3e4);
     try {
       const l = await fetch(i.toString(), {
@@ -10734,10 +10725,9 @@ const Ht = class Ht extends w {
       container: e.auth.projectToken,
       securityTemplateId: e.auth.securityTemplateKey
     } : a = {
-      mode: "session",
+      mode: "sass-key",
       container: e.auth.projectToken,
-      sessionToken: e.auth.sessionToken,
-      companyToken: e.auth.companyToken
+      sassKey: e.auth.sassKey
     }, {
       auth: a,
       targetFolder: i.currentFolderPath || "/",