@riverbankcms/sdk 0.8.0 → 0.9.0

package/README.md

@@ -101,7 +101,7 @@ The SDK provides a multi-layer resilience strategy to keep your site running eve
 1. **In-Memory Cache** - Fast cache with configurable TTL
 2. **Stale-If-Error** - Serves stale cached data when live fetch fails
 3. **Circuit Breaker** - Fail-fast after repeated failures (5 by default)
-4. **Prebuild Fallback** - Static build artifacts as last resort
+4. **Prebuild Fallback** - Static build artifacts as last resort (site, pages, entries, navigation, forms)
 5. **Retry with Backoff** - Automatic retry for transient errors
 
 **Basic Configuration:**
@@ -960,6 +960,125 @@ Blocks can automatically load their data (e.g., blog posts, products) if they ha
 />
 ```
 
+## Image Resolution
+
+Resolve `Media` objects to optimized image URLs. Essential for custom blocks that display images.
+
+### Basic Usage
+
+```tsx
+import { resolveImageUrl, ImagePresets } from '@riverbankcms/sdk/rendering';
+import type { Media } from '@riverbankcms/sdk/rendering';
+
+function MyCustomBlock({ content }: { content: { image: Media } }) {
+  // Use a preset for common sizes
+  const imageUrl = resolveImageUrl(content.image, ImagePresets.card);
+
+  return <img src={imageUrl} alt={content.image.alt ?? ''} />;
+}
+```
+
+### Image Presets
+
+Use presets for consistent, optimized image sizes:
+
+```tsx
+import { resolveImageUrl, ImagePresets } from '@riverbankcms/sdk/rendering';
+
+// Thumbnail (200px width, 80% quality) - for lists, previews
+resolveImageUrl(media, ImagePresets.thumbnail)
+
+// Card (600px width, 80% quality) - for cards, grids
+resolveImageUrl(media, ImagePresets.card)
+
+// Hero (1200px width, 85% quality) - for above-fold content
+resolveImageUrl(media, ImagePresets.hero)
+
+// Full (1920px width, 85% quality) - for backgrounds, large displays
+resolveImageUrl(media, ImagePresets.full)
+```
+
+### Custom Dimensions
+
+Specify exact dimensions when presets don't fit:
+
+```tsx
+// Width only (height auto-calculated to maintain aspect ratio)
+resolveImageUrl(media, { width: 800, quality: 85 })
+
+// Height only (width auto-calculated)
+resolveImageUrl(media, { height: 400, quality: 80 })
+
+// Both dimensions
+resolveImageUrl(media, { width: 800, height: 600, quality: 85 })
+```
+
+### Original Resolution
+
+For rare cases like downloads or print, request the original:
+
+```tsx
+// Full resolution - no transforms applied
+resolveImageUrl(media, { original: true })
+```
+
+### Complete Custom Block Example
+
+```tsx
+import { resolveImageUrl, ImagePresets, RichText } from '@riverbankcms/sdk/rendering';
+import type { SystemBlockComponentProps, Media } from '@riverbankcms/sdk/rendering';
+
+type TeamMemberContent = {
+  name: string;
+  role?: string;
+  photo?: Media;
+  bio?: string;
+};
+
+export function TeamMember({ content }: SystemBlockComponentProps<TeamMemberContent>) {
+  const photoUrl = content.photo
+    ? resolveImageUrl(content.photo, ImagePresets.card)
+    : undefined;
+
+  return (
+    <div className="flex items-start gap-6 p-6">
+      {photoUrl && (
+        <img
+          src={photoUrl}
+          alt={content.photo?.alt || content.name}
+          className="h-24 w-24 rounded-full object-cover"
+        />
+      )}
+      <div>
+        <h3 className="text-xl font-bold">{content.name}</h3>
+        {content.role && <p className="text-gray-600">{content.role}</p>}
+        {content.bio && <RichText content={content.bio} />}
+      </div>
+    </div>
+  );
+}
+```
+
+### How It Works
+
+Images stored in Supabase are served via the transform endpoint when dimensions are specified:
+
+```
+# Without transforms (original resolution - 3000px+)
+https://xxx.supabase.co/storage/v1/object/public/media/sites/abc/originals/photo.jpg
+
+# With transforms (optimized - 600px)
+https://xxx.supabase.co/storage/v1/render/image/public/media/sites/abc/originals/photo.jpg?width=600&quality=80
+```
+
+This reduces image payload significantly (often 10x smaller) while maintaining visual quality.
+
+### Notes
+
+- SVG files are returned as direct URLs (transforms don't apply to vectors)
+- External URLs (`src` field) are returned as-is (can't be transformed)
+- The `Media` type includes `storagePath`, `storageBucket`, `src`, `alt`, and transform metadata
+
 ## Metadata Generation
 
 Generate SEO-optimized metadata for Next.js pages from Riverbank CMS data.
@@ -1069,6 +1188,76 @@ resolutions.forEach(({ path, resolution }) => {
 });
 ```
 
+## Forms
+
+Fetch form definitions for rendering in your frontend. Forms include schema (field definitions) and settings (submit behavior, notifications).
+
+### Fetching Forms
+
+```tsx
+import { createRiverbankClient } from '@riverbankcms/sdk';
+
+const client = createRiverbankClient({
+  apiKey: process.env.RIVERBANK_API_KEY!,
+  baseUrl: process.env.NEXT_PUBLIC_DASHBOARD_URL + '/api',
+});
+
+// Fetch all forms for a site
+const { forms } = await client.getForms({
+  siteId: 'your-site-id',
+});
+
+// Each form includes:
+// - id: Form UUID
+// - slug: URL-friendly identifier
+// - name: Display name
+// - schema: Field definitions
+// - settings: Submit behavior, notifications
+```
+
+### Forms with Prebuild Fallback
+
+Forms support the same resilience features as other content. When prebuild is configured, forms are cached at build time and served as a fallback when the CMS is unavailable:
+
+```tsx
+const client = createRiverbankClient({
+  apiKey: process.env.RIVERBANK_API_KEY!,
+  baseUrl: process.env.RIVERBANK_BASE_URL!,
+  resilience: {
+    prebuildDir: '.riverbank-cache',  // Forms are cached here
+  },
+});
+
+// If CMS is down, cached forms are returned
+const { forms } = await client.getForms({ siteId });
+```
+
+Note: While forms can be rendered from cache during CMS outages, form submissions will fail since they require the live API.
+
+### Rendering Forms
+
+Forms provide schema and settings for building form UI:
+
+```tsx
+function DynamicForm({ form }) {
+  const handleSubmit = async (data) => {
+    await fetch('/api/forms/submit', {
+      method: 'POST',
+      body: JSON.stringify({ formId: form.id, data }),
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {form.schema.fields.map((field) => (
+        <FormField key={field.name} field={field} />
+      ))}
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
 ## Analytics
 
 Track page views, CTA clicks, form submissions, and custom events.
@@ -2584,7 +2773,7 @@ export default defineConfig({
 
 ## CLI
 
-The SDK includes a CLI for syncing your local config to the dashboard.
+The SDK includes a CLI for syncing configuration and content between your local environment and the CMS.
 
 ### push-config
 
@@ -2616,6 +2805,113 @@ npx riverbankcms push-config \
   --dashboard https://www.riverbankcms.com
 ```
 
+### pull
+
+Download content from the CMS to local JSON files:
+
+```bash
+npx riverbankcms pull [scope] [type]
+```
+
+**Scopes:**
+
+| Scope | Description |
+|-------|-------------|
+| (none) / `all` | Pull all content types |
+| `entries` | Pull all entries (or specific type with second argument) |
+| `pages` | Pull all pages |
+| `navigation` | Pull navigation menus |
+| `settings` | Pull site settings |
+| `forms` | Pull form definitions |
+
+**Examples:**
+
+```bash
+# Pull all content
+npx riverbankcms pull
+
+# Pull only forms
+npx riverbankcms pull forms
+
+# Pull entries for a specific content type
+npx riverbankcms pull entries blog-post
+
+# Pull from remote environment
+npx riverbankcms pull --remote
+
+# Sync media files between environments
+npx riverbankcms pull --remote --sync-media
+```
+
+**Output Structure:**
+
+```
+content/
+├── entries/
+│   └── {content-type}.json
+├── pages/
+│   └── {identifier}.json
+├── forms/
+│   └── {slug}.json
+├── navigation.json
+├── settings.json
+└── .meta/
+    └── {entity}.json      # Timestamps for sync detection
+```
+
+### push
+
+Push local content to the CMS with diff-based sync:
+
+```bash
+npx riverbankcms push [scope] [type]
+```
+
+**Scopes:**
+
+| Scope | Description |
+|-------|-------------|
+| (none) / `all` | Push all content types |
+| `entries` | Push all entries (or specific type with second argument) |
+| `pages` | Push pages with blocks |
+| `navigation` | Push navigation menus |
+| `forms` | Push form definitions |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Show what would be pushed without making changes |
+| `--yes` | Skip confirmation (required for `--remote`) |
+| `--force` | Push even if remote is newer |
+| `--json-diff` | Output JSON diff (`summary` or `full`) |
+
+**Examples:**
+
+```bash
+# Preview changes (dry run)
+npx riverbankcms push --dry-run
+
+# Push all content
+npx riverbankcms push
+
+# Push only forms
+npx riverbankcms push forms
+
+# Push to production with confirmation bypass
+npx riverbankcms push --remote --yes
+
+# Get JSON diff for automation
+npx riverbankcms push --dry-run --json-diff=summary
+```
+
+**Sync Behavior:**
+
+- **Creates** new content if identifier/slug doesn't exist
+- **Updates** existing content based on diff
+- **Never deletes** - removing from local doesn't delete from CMS
+- **Stale detection** - warns if remote changed since last pull (use `--force` to override)
+
 ## Next.js Catch-All Page Factory
 
 The SDK provides a `createCatchAllPage()` factory that dramatically reduces boilerplate for Next.js catch-all routes. It handles page/entry routing, preview mode, metadata generation, and error handling in ~10 lines.