@23blocks/block-forms 4.0.0 → 5.0.1

package/CHANGELOG.md

@@ -0,0 +1,363 @@
+## 5.0.1 (2026-02-20)
+
+### 🩹 Fixes
+
+- **@23blocks/block-forms:** remove stale re-exports of FormReference and SubmitFormInstanceRequest ([e26f5dc](https://github.com/23blocks-OS/frontend-sdk/commit/e26f5dc))
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Juan Pelaez
+
+# 5.0.0 (2026-02-20)
+
+### 🩹 Fixes
+
+- ⚠️  **@23blocks/block-forms:** align all types, services and mappers with API strong params ([31ead5f](https://github.com/23blocks-OS/frontend-sdk/commit/31ead5f))
+
+### ⚠️  Breaking Changes
+
+- **@23blocks/block-forms:** align all types, services and mappers with API strong params  ([31ead5f](https://github.com/23blocks-OS/frontend-sdk/commit/31ead5f))
+  Complete rewrite of forms block to match actual Rails API.
+  Root keys fixed: landing_instance→landing, survey_instance→survey,
+  mail_template→template, form_submission→responses, report→query_params.
+  Field renames: phone→phoneNumber, scheduledAt→startAt, schema→formFields,
+  uiSchema→datasource, subject→fromSubject, htmlContent→templateHtml,
+  textContent→templateText, providerTemplateId→templateName, fromEmail→fromAddress.
+  Removed invented fields: FormReference, SubmitFormInstanceRequest,
+  referrerEmail, refereeName, refereePhone, data (on instances), enabled (on Form).
+  Added 80+ missing fields across all services including source tracking,
+  visitor attribution, assigned-to fields, form configuration options,
+  and CRM sync batch parameters.
+  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Juan Pelaez
+
+# 4.0.0 (2026-02-20)
+
+### 🩹 Fixes
+
+- ⚠️  replace appId with apiKey across all block configs to align with BlockConfig contract ([f81626d](https://github.com/23blocks-OS/frontend-sdk/commit/f81626d))
+- resolve typecheck errors across all block packages ([6089324](https://github.com/23blocks-OS/frontend-sdk/commit/6089324))
+
+### ⚠️  Breaking Changes
+
+- replace appId with apiKey across all block configs to align with BlockConfig contract  ([f81626d](https://github.com/23blocks-OS/frontend-sdk/commit/f81626d))
+  Block config no longer accepts appId. Use apiKey instead.
+  Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.3.1
+- Updated @23blocks/contracts to 2.3.1
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Juan Pelaez
+
+## 3.3.0 (2026-02-17)
+
+### 🚀 Features
+
+- add health() method to all 18 blocks for service connectivity checks ([73514a3](https://github.com/23blocks-OS/frontend-sdk/commit/73514a3))
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.3.0
+- Updated @23blocks/contracts to 2.3.0
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Juan Pelaez
+
+## 3.2.0 (2026-02-08)
+
+### 🚀 Features
+
+- add comprehensive JSDoc documentation and llms.txt for AI agent consumption ([fd97df2](https://github.com/23blocks-OS/frontend-sdk/commit/fd97df2))
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.2.0
+- Updated @23blocks/contracts to 2.2.0
+
+### ❤️ Thank You
+
+- Claude Opus 4.6
+- Juan Pelaez
+
+## 3.1.9 (2026-02-07)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.1.3
+- Updated @23blocks/contracts to 2.1.3
+
+## 3.1.8 (2026-02-06)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.1.2
+- Updated @23blocks/contracts to 2.1.2
+
+## 3.1.7 (2026-01-20)
+
+### 🩹 Fixes
+
+- resolve TypeScript errors and add PostTemplate validation support ([250d284](https://github.com/23blocks-OS/frontend-sdk/commit/250d284))
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.1.1
+- Updated @23blocks/contracts to 2.1.1
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.1.6 (2026-01-16)
+
+### 🩹 Fixes
+
+- **mappers:** remove dangerous uniqueId fallback to resource.id ([e96c555](https://github.com/23blocks-OS/frontend-sdk/commit/e96c555))
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.1.5 (2026-01-13)
+
+### 🚀 Features
+
+- **forms,crm:** add OTP verification for public forms and document expiration tracking ([426b87d](https://github.com/23blocks-OS/frontend-sdk/commit/426b87d))
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.1.4 (2026-01-05)
+
+### 🩹 Fixes
+
+- **forms:** rename create to submit for landing and subscription forms ([7c7126f](https://github.com/23blocks-OS/frontend-sdk/commit/7c7126f))
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.1.3 (2026-01-05)
+
+### 🚀 Features
+
+- ⚠️  **forms:** rename publicForms to applicationForms ([0c5cad6](https://github.com/23blocks-OS/frontend-sdk/commit/0c5cad6))
+
+### ⚠️  Breaking Changes
+
+- **forms:** rename publicForms to applicationForms  ([0c5cad6](https://github.com/23blocks-OS/frontend-sdk/commit/0c5cad6))
+  publicForms renamed to applicationForms
+  🤖 Generated with [Claude Code](https://claude.com/claude-code)
+  Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.1.2 (2026-01-04)
+
+### 🩹 Fixes
+
+- **block-forms:** export all types, services, and mappers ([d43b143](https://github.com/23blocks-OS/frontend-sdk/commit/d43b143))
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.1.1 (2026-01-04)
+
+### 🚀 Features
+
+- ⚠️  **block-forms:** complete Forms API with all missing endpoints ([93bd809](https://github.com/23blocks-OS/frontend-sdk/commit/93bd809))
+
+### ⚠️  Breaking Changes
+
+- **block-forms:** complete Forms API with all missing endpoints  ([93bd809](https://github.com/23blocks-OS/frontend-sdk/commit/93bd809))
+  FormInstancesService and FormSchemasService now use
+  nested routes requiring formUniqueId as first parameter
+  New services:
+  - FormSchemaVersionsService: full CRUD + publish for schema versions
+  - CrmSyncService: CRM sync operations (sync, batch, retry, status)
+  Updated services:
+  - FormInstancesService: nested routes /forms/:id/instances/*
+    - Added: start(), submit(), cancel(), resendMagicLink()
+  - FormSchemasService: nested routes /forms/:id/schemas/*
+  - FormSetsService: Added match() and autoAssign()
+  All services now align with the backend API routes:
+  - Forms: /forms/*
+  - Schemas: /forms/:id/schemas/*
+  - Schema Versions: /forms/:id/schemas/:id/versions/*
+  - Instances: /forms/:id/instances/*
+  - Form Sets: /form_sets/* (with match/auto_assign)
+  - CRM Sync: /crm/*
+  🤖 Generated with [Claude Code](https://claude.com/claude-code)
+  Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.1.0 (2026-01-01)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.1.0
+- Updated @23blocks/contracts to 2.1.0
+
+## 3.0.2 (2025-12-31)
+
+### 🩹 Fixes
+
+- replace PATCH with PUT across all services ([6339334](https://github.com/23blocks-OS/frontend-sdk/commit/6339334))
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 3.0.1 (2025-12-17)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.0.1
+- Updated @23blocks/contracts to 2.0.1
+
+# 3.0.0 (2025-12-17)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 3.0.0
+- Updated @23blocks/contracts to 2.0.0
+
+## 2.1.0 (2025-12-15)
+
+### 🚀 Features
+
+- expand SDK API coverage for Content, Files, Forms, Geolocation blocks ([8e5c709](https://github.com/23blocks-OS/frontend-sdk/commit/8e5c709))
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+# 2.0.0 (2025-12-15)
+
+### 🩹 Fixes
+
+- ⚠️  wrap all API request parameters with correct Rails object keys ([192ad70](https://github.com/23blocks-OS/frontend-sdk/commit/192ad70))
+
+### ⚠️  Breaking Changes
+
+- wrap all API request parameters with correct Rails object keys  ([192ad70](https://github.com/23blocks-OS/frontend-sdk/commit/192ad70))
+  All service methods now correctly wrap request bodies
+  with Rails-expected parameter keys (e.g., `user:`, `contact:`, `order:`).
+  This fixes the critical issue where API requests were failing validation
+  because parameters were sent flat instead of wrapped.
+  Affected blocks:
+  - block-authentication: auth, users, guests, apps, subscriptions, api-keys, roles
+  - block-crm: contacts, accounts, leads, opportunities, meetings, quotes
+  - block-company: companies, departments, teams, team-members, quarters
+  - block-content: posts, comments, categories, tags
+  - block-products: products, cart, catalog
+  - block-sales: orders, order-details, payments, subscriptions
+  - block-conversations: messages, groups, draft-messages, notifications
+  - block-wallet: wallets, authorization-codes
+  - block-files: storage-files, entity-files, file-schemas
+  - block-forms: forms, form-schemas, form-sets, form-instances
+  - block-assets: assets, asset-events, asset-audits
+  - block-campaigns: campaigns, campaign-media, audiences, landing-pages
+  - block-geolocation: locations, addresses, areas, regions, routes, bookings, premises
+  - block-rewards: rewards, coupons, loyalty, badges
+  - block-onboarding: onboardings, flows, user-journeys, user-identities
+  - block-university: courses, lessons, enrollments, assignments, submissions
+  - block-jarvis: agents, prompts, workflows, conversations
+  Consumer API remains unchanged - this is an internal fix.
+  🤖 Generated with [Claude Code](https://claude.com/claude-code)
+  Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 2.0.0
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez
+
+## 1.0.4 (2025-12-14)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 1.0.4
+- Updated @23blocks/contracts to 1.0.4
+
+## 1.0.3 (2025-12-14)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 1.0.3
+- Updated @23blocks/contracts to 1.0.3
+
+## 1.0.2 (2025-12-14)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 1.0.2
+- Updated @23blocks/contracts to 1.0.2
+
+## 1.0.1 (2025-12-14)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 1.0.1
+- Updated @23blocks/contracts to 1.0.1
+
+# 1.0.0 (2025-12-13)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 1.0.0
+- Updated @23blocks/contracts to 1.0.0
+
+## 0.2.1 (2025-12-13)
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 0.1.2
+- Updated @23blocks/contracts to 0.1.2
+
+## 0.2.0 (2025-12-13)
+
+### 🚀 Features
+
+- add all block packages with React and Angular bindings ([bbeecf7](https://github.com/23blocks-OS/frontend-sdk/commit/bbeecf7))
+
+### 🧱 Updated Dependencies
+
+- Updated @23blocks/jsonapi-codec to 0.1.1
+- Updated @23blocks/contracts to 0.1.1
+
+### ❤️ Thank You
+
+- Claude Opus 4.5
+- Juan Pelaez

package/README.md

@@ -1,6 +1,6 @@
 # @23blocks/block-forms
 
-Forms block for the 23blocks SDK - dynamic forms, schemas, and submissions.
+Forms block for the 23blocks SDK - dynamic forms, schemas, submissions, landings, surveys, appointments, subscriptions, referrals, and mail templates.
 
 [![npm version](https://img.shields.io/npm/v/@23blocks/block-forms.svg)](https://www.npmjs.com/package/@23blocks/block-forms)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -16,9 +16,18 @@ npm install @23blocks/block-forms @23blocks/transport-http
 This package provides form building and submission functionality including:
 
 - **Forms** - Form definitions and configurations
-- **Form Schemas** - Field definitions and validations
-- **Form Instances** - Individual form submissions
-- **Form Sets** - Groups of related forms
+- **Form Schemas** - Field definitions with datasource configuration
+- **Form Schema Versions** - Published schema versions
+- **Form Instances** - App form assignments with responses
+- **Form Sets** - Groups of related form schemas with auto-assignment
+- **Landings** - Landing page form submissions
+- **Surveys** - Survey form submissions with magic link support
+- **Appointments** - Appointment scheduling with location and assignment
+- **Subscriptions** - Newsletter and subscription management
+- **Referrals** - Referral tracking with source attribution
+- **Mail Templates** - Email template configuration
+- **Application Forms** - Public form submission and draft workflows
+- **CRM Sync** - Synchronize form data with CRM
 
 ## Quick Start
 
@@ -41,14 +50,13 @@ const forms = createFormsBlock(transport, {
 // List forms
 const { data: formList } = await forms.forms.list();
 
-// Submit a form
-const submission = await forms.formInstances.submit({
-  formId: 'form-id',
-  data: {
-    name: 'John Doe',
-    email: 'john@example.com',
-    message: 'Hello!',
-  },
+// Create a landing submission
+await forms.landings.create({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phoneNumber: '+1234567890',
+  message: 'Hello!',
 });
 ```
 
@@ -59,7 +67,7 @@ const submission = await forms.formInstances.submit({
 ```typescript
 // List forms
 const { data: formList } = await forms.forms.list({
-  limit: 20,
+  perPage: 20,
   status: 'active',
 });
 
@@ -68,10 +76,12 @@ const form = await forms.forms.get('form-id');
 
 // Create form
 const newForm = await forms.forms.create({
+  code: 'contact-form',
   name: 'Contact Form',
   description: 'Contact us form',
-  status: 'active',
-  schemaId: 'schema-id',
+  formType: 'landing',
+  sendConfirmationMail: true,
+  requireOtpVerification: false,
 });
 
 // Update form
@@ -88,97 +98,51 @@ await forms.forms.delete('form-id');
 
 ```typescript
 // List schemas
-const { data: schemas } = await forms.formSchemas.list();
-
-// Get schema by ID
-const schema = await forms.formSchemas.get('schema-id');
+const { data: schemas } = await forms.formSchemas.list({
+  formUniqueId: 'form-id',
+});
 
 // Create schema
 const newSchema = await forms.formSchemas.create({
+  formUniqueId: 'form-id',
   name: 'Contact Schema',
-  fields: [
-    {
-      name: 'name',
-      type: 'text',
-      label: 'Your Name',
-      required: true,
-      validation: { minLength: 2, maxLength: 100 },
-    },
-    {
-      name: 'email',
-      type: 'email',
-      label: 'Email Address',
-      required: true,
-    },
-    {
-      name: 'message',
-      type: 'textarea',
-      label: 'Message',
-      required: true,
-      validation: { minLength: 10, maxLength: 1000 },
-    },
-    {
-      name: 'priority',
-      type: 'select',
-      label: 'Priority',
-      options: ['low', 'medium', 'high'],
-      defaultValue: 'medium',
-    },
-  ],
+  formFields: {
+    fields: [
+      { name: 'name', type: 'text', required: true },
+      { name: 'email', type: 'email', required: true },
+    ],
+  },
+  datasource: {},
 });
 
 // Update schema
 await forms.formSchemas.update('schema-id', {
-  fields: [
-    // updated fields
-  ],
+  formFields: { /* updated fields */ },
 });
-
-// Delete schema
-await forms.formSchemas.delete('schema-id');
 ```
 
-### formInstances - Form Submissions
+### formInstances - App Form Instances
 
 ```typescript
-// List submissions
-const { data: submissions } = await forms.formInstances.list({
-  formId: 'form-id',
-  status: 'submitted',
+// List instances
+const { data: instances } = await forms.formInstances.list({
+  userUniqueId: 'user-id',
+  status: 'active',
 });
 
-// Get submission by ID
-const submission = await forms.formInstances.get('instance-id');
-
-// Create a draft instance
-const draft = await forms.formInstances.create({
-  formId: 'form-id',
-  data: {
-    name: 'John',
-  },
-  status: 'draft',
+// Create an instance (assignment)
+const instance = await forms.formInstances.create('form-id', {
+  assignedToEmail: 'user@example.com',
+  assignedToName: 'John Doe',
+  assignedByName: 'Admin',
+  expiresAt: '2025-12-31',
 });
 
-// Update draft
+// Update instance
 await forms.formInstances.update('instance-id', {
-  data: {
-    name: 'John Doe',
-    email: 'john@example.com',
-  },
-});
-
-// Submit form
-const submitted = await forms.formInstances.submit({
-  formId: 'form-id',
-  data: {
-    name: 'John Doe',
-    email: 'john@example.com',
-    message: 'Hello, I have a question...',
-  },
+  responses: [{ fieldId: 'name', value: 'John Doe' }],
+  status: 'completed',
 });
-
-// Delete submission
-await forms.formInstances.delete('instance-id');
 ```
 
 ### formSets - Form Set Management
@@ -187,30 +151,60 @@ await forms.formInstances.delete('instance-id');
 // List form sets
 const { data: sets } = await forms.formSets.list();
 
-// Get form set by ID
-const formSet = await forms.formSets.get('set-id');
-
 // Create form set
 const newSet = await forms.formSets.create({
+  code: 'onboarding',
   name: 'Onboarding Forms',
   description: 'Forms required for new user onboarding',
-  formReferences: [
-    { formId: 'form-1', order: 1, required: true },
-    { formId: 'form-2', order: 2, required: false },
-    { formId: 'form-3', order: 3, required: true },
+  enforceSequential: true,
+  expirationDays: 30,
+  formSetItemsAttributes: [
+    { formSchemaUniqueId: 'schema-1', displayOrder: 1, required: true },
+    { formSchemaUniqueId: 'schema-2', displayOrder: 2, required: false },
   ],
 });
 
-// Update form set
-await forms.formSets.update('set-id', {
-  formReferences: [
-    { formId: 'form-1', order: 1, required: true },
-    { formId: 'form-2', order: 2, required: true },
-  ],
+// Match form set
+const match = await forms.formSets.match({
+  userUniqueId: 'user-id',
+  category: 'onboarding',
 });
 
-// Delete form set
-await forms.formSets.delete('set-id');
+// Auto-assign form set
+await forms.formSets.autoAssign({
+  userUniqueId: 'user-id',
+  formSetUniqueId: 'set-id',
+  assignedByName: 'System',
+});
+```
+
+### landings - Landing Form Submissions
+
+```typescript
+const landing = await forms.landings.create({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phoneNumber: '+1234567890',
+  message: 'I am interested in your product',
+  source: 'website',
+});
+```
+
+### appointments - Appointment Scheduling
+
+```typescript
+const appointment = await forms.appointments.create({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  phoneNumber: '+1234567890',
+  startAt: '2025-06-15T10:00:00Z',
+  endAt: '2025-06-15T11:00:00Z',
+  locationName: 'Main Office',
+  locationAddress: '123 Main St',
+  assignedToName: 'Dr. Smith',
+});
 ```
 
 ## Types
@@ -219,57 +213,32 @@ await forms.formSets.delete('set-id');
 import type {
   Form,
   FormSchema,
+  FormSchemaVersion,
   FormInstance,
   FormSet,
-  FormReference,
+  FormSetItem,
+  Landing,
+  Survey,
+  Appointment,
+  Subscription,
+  Referral,
+  MailTemplate,
   CreateFormRequest,
   CreateFormSchemaRequest,
   CreateFormInstanceRequest,
-  SubmitFormInstanceRequest,
   CreateFormSetRequest,
 } from '@23blocks/block-forms';
 ```
 
-### Form
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | Form ID |
-| `uniqueId` | `string` | Unique identifier |
-| `name` | `string` | Form name |
-| `description` | `string` | Form description |
-| `status` | `string` | active, inactive, archived |
-| `schemaId` | `string` | Associated schema ID |
-| `schema` | `FormSchema` | Schema details |
-
-### FormSchema
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | Schema ID |
-| `name` | `string` | Schema name |
-| `fields` | `Field[]` | Field definitions |
-| `validations` | `object` | Form-level validations |
-
-### FormInstance
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `id` | `string` | Instance ID |
-| `formId` | `string` | Parent form ID |
-| `data` | `object` | Submitted data |
-| `status` | `string` | draft, submitted, approved, rejected |
-| `submittedAt` | `Date` | Submission timestamp |
-
 ## Error Handling
 
 ```typescript
 import { isBlockErrorException, ErrorCodes } from '@23blocks/contracts';
 
 try {
-  await forms.formInstances.submit({
-    formId: 'form-id',
-    data: { name: '' }, // Invalid - name is required
+  await forms.landings.create({
+    firstName: 'John',
+    email: 'john@example.com',
   });
 } catch (error) {
   if (isBlockErrorException(error)) {