@forms.expert/sdk 0.1.0

package/README.md

@@ -0,0 +1,331 @@
+# Forms Expert SDK
+
+Embeddable forms SDK for submitting forms via the Forms Expert API.
+
+## Installation
+
+```bash
+npm install @forms-expert/sdk
+```
+
+## Quick Start
+
+### Vanilla JavaScript (CDN)
+
+```html
+<!-- Include the SDK -->
+<script src="https://cdn.mira.io/forms-sdk/latest/vanilla/index.global.js"></script>
+
+<!-- Create a container with data attributes -->
+<div
+  data-forms-expert="contact"
+  data-api-key="pk_live_xxxxxxxxxxxx"
+  data-resource-id="your-resource-id"
+></div>
+
+<!-- Forms will auto-initialize on page load -->
+```
+
+### Vanilla JavaScript (Module)
+
+```javascript
+import { FormWidget } from '@forms-expert/sdk/vanilla';
+
+const widget = new FormWidget(
+  {
+    apiKey: 'pk_live_xxxxxxxxxxxx',
+    resourceId: 'your-resource-id',
+  },
+  {
+    target: '#my-form',
+    slug: 'contact',
+    onSuccess: (response) => {
+      console.log('Form submitted:', response.submissionId);
+    },
+    onError: (error) => {
+      console.error('Submission failed:', error);
+    },
+  }
+);
+
+widget.init();
+```
+
+### React
+
+```tsx
+import { FormsExpertForm } from '@forms-expert/sdk/react';
+
+function ContactPage() {
+  return (
+    <FormsExpertForm
+      config={{
+        apiKey: 'pk_live_xxxxxxxxxxxx',
+        resourceId: 'your-resource-id',
+      }}
+      slug="contact"
+      submitText="Send Message"
+      onSuccess={(response) => {
+        console.log('Submitted:', response.submissionId);
+      }}
+    />
+  );
+}
+```
+
+### React Hook
+
+```tsx
+import { useForm, FormsProvider } from '@forms-expert/sdk/react';
+
+// With provider
+function App() {
+  return (
+    <FormsProvider
+      config={{
+        apiKey: 'pk_live_xxxxxxxxxxxx',
+        resourceId: 'your-resource-id',
+      }}
+    >
+      <ContactForm />
+    </FormsProvider>
+  );
+}
+
+function ContactForm() {
+  const form = useForm({
+    slug: 'contact',
+    onSuccess: (response) => alert('Thanks!'),
+  });
+
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await form.submit();
+  };
+
+  if (form.isSubmitted) {
+    return <p>Thank you for your submission!</p>;
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={form.values.email || ''}
+        onChange={(e) => form.setValue('email', e.target.value)}
+      />
+      {form.errors.email && <span>{form.errors.email}</span>}
+
+      <textarea
+        value={form.values.message || ''}
+        onChange={(e) => form.setValue('message', e.target.value)}
+      />
+      {form.errors.message && <span>{form.errors.message}</span>}
+
+      <button type="submit" disabled={form.isLoading}>
+        {form.isLoading ? 'Sending...' : 'Submit'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Vue 3
+
+```vue
+<script setup>
+import { useForm } from '@forms-expert/sdk/vue';
+
+const form = useForm({
+  slug: 'contact',
+  config: {
+    apiKey: 'pk_live_xxxxxxxxxxxx',
+    resourceId: 'your-resource-id',
+  },
+  onSuccess: (response) => {
+    alert('Form submitted!');
+  },
+});
+
+const handleSubmit = async () => {
+  await form.submit();
+};
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <div v-if="form.isSubmitted.value">
+      Thank you for your submission!
+    </div>
+    
+    <template v-else>
+      <input
+        type="email"
+        :value="form.values.value.email"
+        @input="form.setValue('email', $event.target.value)"
+      />
+      <span v-if="form.errors.value.email">{{ form.errors.value.email }}</span>
+
+      <button type="submit" :disabled="form.isLoading.value">
+        {{ form.isLoading.value ? 'Sending...' : 'Submit' }}
+      </button>
+    </template>
+  </form>
+</template>
+```
+
+## Core SDK
+
+For programmatic form submission without UI:
+
+```typescript
+import { FormsSDK } from '@forms-expert/sdk';
+
+const sdk = new FormsSDK({
+  apiKey: 'pk_live_xxxxxxxxxxxx',
+  resourceId: 'your-resource-id',
+});
+
+// Check if form is active
+const status = await sdk.isActive('contact');
+if (!status.active) {
+  console.error('Form not available');
+}
+
+// Validate data
+const validation = await sdk.validate('contact', {
+  email: 'user@example.com',
+  message: 'Hello!',
+});
+
+if (!validation.valid) {
+  console.error('Validation errors:', validation.errors);
+}
+
+// Submit form
+const response = await sdk.submit('contact', {
+  email: 'user@example.com',
+  message: 'Hello!',
+});
+
+console.log('Submission ID:', response.submissionId);
+```
+
+### Form Handler
+
+For more control, use the FormHandler:
+
+```typescript
+const handler = sdk.form('contact', {
+  onSubmitStart: () => console.log('Submitting...'),
+  onSubmitSuccess: (response) => console.log('Success!', response),
+  onSubmitError: (error) => console.error('Error:', error),
+  onValidationError: (errors) => console.error('Validation:', errors),
+});
+
+// Initialize to get form config
+await handler.initialize();
+
+// Check captcha requirement
+if (handler.requiresCaptcha()) {
+  const provider = handler.getCaptchaProvider(); // 'turnstile' | 'recaptcha' | 'hcaptcha'
+  // Initialize captcha widget...
+}
+
+// Submit with validation
+await handler.submit({ email: 'user@example.com' });
+```
+
+## Configuration
+
+### SDK Config
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | Yes | Publishable API key (`pk_live_*` or `pk_test_*`) |
+| `resourceId` | `string` | Yes | Resource ID containing the form |
+| `baseUrl` | `string` | No | API base URL (default: `https://api.formsapp.io/api/v1`) |
+
+### Widget Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `target` | `string \| HTMLElement` | - | Target element or selector |
+| `slug` | `string` | - | Form slug |
+| `submitText` | `string` | `'Submit'` | Submit button text |
+| `showBranding` | `boolean` | `true` | Show "Powered by Mira" branding |
+| `resetOnSuccess` | `boolean` | `false` | Reset form after successful submission |
+| `redirectUrl` | `string` | - | Redirect URL after success |
+| `onSuccess` | `function` | - | Success callback |
+| `onError` | `function` | - | Error callback |
+| `onValidationError` | `function` | - | Validation error callback |
+
+## Data Attributes (Auto-init)
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `data-forms-expert` | Yes | Form slug |
+| `data-api-key` | Yes | Publishable API key |
+| `data-resource-id` | Yes | Resource ID |
+| `data-base-url` | No | Custom API base URL |
+| `data-submit-text` | No | Submit button text |
+| `data-branding` | No | Set to `'false'` to hide branding |
+| `data-reset` | No | Set to `'true'` to reset after submission |
+
+## Error Handling
+
+```typescript
+import { FormsError, FormValidationError } from '@forms-expert/sdk';
+
+try {
+  await sdk.submit('contact', data);
+} catch (error) {
+  if (error instanceof FormValidationError) {
+    // Handle validation errors
+    error.errors.forEach(({ field, message }) => {
+      console.log(`${field}: ${message}`);
+    });
+  } else if (error instanceof FormsError) {
+    // Handle API errors
+    console.error(`${error.code}: ${error.message}`);
+    
+    if (error.code === 'FORM_RATE_LIMIT_EXCEEDED') {
+      // Retry after delay
+      setTimeout(() => retry(), error.retryAfter * 1000);
+    }
+  }
+}
+```
+
+### Error Codes
+
+| Code | Description |
+|------|-------------|
+| `FORM_NOT_FOUND` | Form does not exist |
+| `FORM_NOT_PUBLISHED` | Form is not published |
+| `VALIDATION_ERROR` | Form data validation failed |
+| `CAPTCHA_REQUIRED` | CAPTCHA token missing |
+| `CAPTCHA_FAILED` | CAPTCHA verification failed |
+| `FORM_RATE_LIMIT_EXCEEDED` | Form-specific rate limit exceeded |
+| `GLOBAL_RATE_LIMIT_EXCEEDED` | IP rate limit exceeded |
+| `ORIGIN_NOT_ALLOWED` | Request origin not in whitelist |
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  FormField,
+  FormSchema,
+  FormStyling,
+  FormStatusResponse,
+  ValidationResponse,
+  SubmissionResponse,
+  FormsSDKConfig,
+} from '@forms-expert/sdk';
+```
+
+## License
+
+MIT

package/dist/core/index.cjs

@@ -0,0 +1,365 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// core/index.ts
+var core_exports = {};
+__export(core_exports, {
+  FormHandler: () => FormHandler,
+  FormValidationError: () => FormValidationError,
+  FormsApiClient: () => FormsApiClient,
+  FormsError: () => FormsError,
+  FormsSDK: () => FormsSDK
+});
+module.exports = __toCommonJS(core_exports);
+
+// core/types.ts
+var FormsError = class extends Error {
+  constructor(message, code, statusCode, retryAfter) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.retryAfter = retryAfter;
+    this.name = "FormsError";
+  }
+};
+var FormValidationError = class extends Error {
+  constructor(errors) {
+    super("Validation failed");
+    this.errors = errors;
+    this.name = "FormValidationError";
+  }
+};
+
+// core/api-client.ts
+var FormsApiClient = class {
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.resourceId = config.resourceId;
+    this.baseUrl = (config.baseUrl || "https://api.formsapp.io/api/v1").replace(/\/$/, "");
+  }
+  /**
+   * Build URL with token query parameter
+   */
+  buildUrl(path) {
+    const separator = path.includes("?") ? "&" : "?";
+    return `${this.baseUrl}${path}${separator}token=${encodeURIComponent(this.apiKey)}`;
+  }
+  /**
+   * Make an API request
+   */
+  async request(method, path, body) {
+    const url = this.buildUrl(path);
+    const response = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    const data = await response.json();
+    if (!response.ok) {
+      throw new FormsError(
+        data.message || "Request failed",
+        data.code || "UNKNOWN_ERROR",
+        response.status,
+        data.retryAfter
+      );
+    }
+    return data;
+  }
+  /**
+   * Check if form is active and get configuration
+   */
+  async isActive(slug) {
+    return this.request("GET", `/f/${this.resourceId}/${slug}/is-active`);
+  }
+  /**
+   * Validate form data without submitting
+   */
+  async validate(slug, data) {
+    return this.request("POST", `/f/${this.resourceId}/${slug}/validate`, {
+      data
+    });
+  }
+  /**
+   * Submit form data (supports files)
+   */
+  async submit(slug, data, options) {
+    const url = this.buildUrl(`/f/${this.resourceId}/${slug}`);
+    const hasFiles = Object.values(data).some(
+      (v) => v instanceof File || v instanceof FileList && v.length > 0
+    );
+    if (hasFiles || options?.onProgress) {
+      return this.submitWithFormData(url, data, options);
+    }
+    return this.request("POST", `/f/${this.resourceId}/${slug}`, {
+      data,
+      pageUrl: options?.pageUrl || (typeof window !== "undefined" ? window.location.href : void 0),
+      captchaToken: options?.captchaToken
+    });
+  }
+  /**
+   * Submit with FormData (for file uploads with progress tracking)
+   */
+  submitWithFormData(url, data, options) {
+    return new Promise((resolve, reject) => {
+      const formData = new FormData();
+      for (const [key, value] of Object.entries(data)) {
+        if (value instanceof File) {
+          formData.append(key, value);
+        } else if (value instanceof FileList) {
+          Array.from(value).forEach((file) => formData.append(key, file));
+        } else if (value !== void 0 && value !== null) {
+          formData.append(`data[${key}]`, String(value));
+        }
+      }
+      const pageUrl = options?.pageUrl || (typeof window !== "undefined" ? window.location.href : "");
+      if (pageUrl) {
+        formData.append("pageUrl", pageUrl);
+      }
+      if (options?.captchaToken) {
+        formData.append("captchaToken", options.captchaToken);
+      }
+      const xhr = new XMLHttpRequest();
+      if (options?.onProgress) {
+        xhr.upload.addEventListener("progress", (event) => {
+          if (event.lengthComputable) {
+            options.onProgress({
+              loaded: event.loaded,
+              total: event.total,
+              percentage: Math.round(event.loaded / event.total * 100)
+            });
+          }
+        });
+      }
+      xhr.addEventListener("load", () => {
+        try {
+          const response = JSON.parse(xhr.responseText);
+          if (xhr.status >= 200 && xhr.status < 300) {
+            resolve(response);
+          } else {
+            reject(new FormsError(
+              response.message || "Submission failed",
+              response.code || "UNKNOWN_ERROR",
+              xhr.status,
+              response.retryAfter
+            ));
+          }
+        } catch {
+          reject(new FormsError("Invalid response", "PARSE_ERROR", xhr.status));
+        }
+      });
+      xhr.addEventListener("error", () => {
+        reject(new FormsError("Network error", "NETWORK_ERROR", 0));
+      });
+      xhr.addEventListener("abort", () => {
+        reject(new FormsError("Request aborted", "ABORTED", 0));
+      });
+      xhr.open("POST", url);
+      xhr.send(formData);
+    });
+  }
+  /**
+   * Track a form view (for analytics completion rate)
+   */
+  async trackView(slug) {
+    const url = this.buildUrl(`/f/${this.resourceId}/${slug}/view`);
+    await fetch(url, { method: "POST", headers: { "Content-Type": "application/json" } }).catch(() => {
+    });
+  }
+  /**
+   * Get resource ID
+   */
+  getResourceId() {
+    return this.resourceId;
+  }
+  /**
+   * Get base URL
+   */
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+};
+
+// core/forms-sdk.ts
+var FormHandler = class {
+  constructor(apiClient, slug, options = {}) {
+    this.config = null;
+    this.apiClient = apiClient;
+    this.slug = slug;
+    this.options = options;
+  }
+  /**
+   * Initialize form handler and fetch configuration
+   */
+  async initialize() {
+    this.config = await this.apiClient.isActive(this.slug);
+    if (this.options.trackViews) {
+      this.apiClient.trackView(this.slug);
+    }
+    return this.config;
+  }
+  /**
+   * Get cached form configuration
+   */
+  getConfig() {
+    return this.config;
+  }
+  /**
+   * Check if form is active
+   */
+  isActive() {
+    return this.config?.active ?? false;
+  }
+  /**
+   * Check if captcha is required
+   */
+  requiresCaptcha() {
+    return this.config?.settings?.captcha?.enabled ?? false;
+  }
+  /**
+   * Get captcha provider
+   */
+  getCaptchaProvider() {
+    return this.config?.settings?.captcha?.provider;
+  }
+  /**
+   * Get form schema
+   */
+  getSchema() {
+    return this.config?.schema;
+  }
+  /**
+   * Validate form data
+   */
+  async validate(data) {
+    return this.apiClient.validate(this.slug, data);
+  }
+  /**
+   * Submit form data
+   */
+  async submit(data, options) {
+    this.options.onSubmitStart?.();
+    try {
+      if (this.config?.mode === "schema") {
+        const validation = await this.validate(data);
+        if (!validation.valid) {
+          this.options.onValidationError?.(validation.errors);
+          throw new FormValidationError(validation.errors);
+        }
+      }
+      const response = await this.apiClient.submit(this.slug, data, options);
+      this.options.onSubmitSuccess?.(response);
+      return response;
+    } catch (error) {
+      if (error instanceof FormsError) {
+        this.options.onSubmitError?.(error);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Get success message from config
+   */
+  getSuccessMessage() {
+    return this.config?.settings?.successMessage || "Form submitted successfully!";
+  }
+  /**
+   * Get redirect URL from config
+   */
+  getRedirectUrl() {
+    return this.config?.settings?.redirectUrl;
+  }
+};
+var FormsSDK = class {
+  constructor(config) {
+    this.apiClient = new FormsApiClient(config);
+  }
+  /**
+   * Check if form is active and get configuration
+   */
+  async isActive(slug) {
+    return this.apiClient.isActive(slug);
+  }
+  /**
+   * Validate form data without submitting
+   */
+  async validate(slug, data) {
+    return this.apiClient.validate(slug, data);
+  }
+  /**
+   * Submit form data
+   */
+  async submit(slug, data, options) {
+    return this.apiClient.submit(slug, data, options);
+  }
+  /**
+   * Create a form handler for a specific form
+   */
+  form(slug, options) {
+    return new FormHandler(this.apiClient, slug, options);
+  }
+  /**
+   * Track a form view (for analytics completion rate)
+   */
+  async trackView(slug) {
+    return this.apiClient.trackView(slug);
+  }
+  /**
+   * Submit with retry logic for rate limits
+   */
+  async submitWithRetry(slug, data, options) {
+    const maxRetries = options?.maxRetries ?? 3;
+    let lastError = null;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        return await this.submit(slug, data, options);
+      } catch (error) {
+        lastError = error;
+        if (error instanceof FormsError) {
+          if ([
+            "VALIDATION_ERROR",
+            "CAPTCHA_REQUIRED",
+            "ORIGIN_NOT_ALLOWED"
+          ].includes(error.code)) {
+            throw error;
+          }
+          if (error.code.includes("RATE_LIMIT")) {
+            const retryAfter = error.retryAfter || Math.pow(2, attempt) * 1e3;
+            await new Promise((resolve) => setTimeout(resolve, retryAfter));
+            continue;
+          }
+        }
+        await new Promise(
+          (resolve) => setTimeout(resolve, Math.pow(2, attempt) * 1e3)
+        );
+      }
+    }
+    throw lastError;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FormHandler,
+  FormValidationError,
+  FormsApiClient,
+  FormsError,
+  FormsSDK
+});
+//# sourceMappingURL=index.cjs.map