Skip to content

README.md

Latest commit

 

History

History
327 lines (231 loc) · 10.7 KB

README.md

File metadata and controls

327 lines (231 loc) · 10.7 KB

CADit Embed SDK

Embed a full 3D design editor in your web app — let users create, edit, and export 3D models without leaving your platform.

CADit is a browser-based 3D CAD editor. The Embed SDK lets you drop it into an iframe and communicate via postMessage for STL export, design import, and authenticated user sessions.

CADit embedded in a partner application

Quick Start

1. Add the iframe

<iframe
  id="caditFrame"
  src="https://app.cadit.app/new?embed=true&partnerName=YourApp"
  allow="clipboard-read; clipboard-write"
  style="width: 100%; height: 600px; border: none;"
></iframe>

2. Listen for messages from CADit

const CADIT_ORIGIN = 'https://app.cadit.app';
const caditFrame = document.getElementById('caditFrame');

window.addEventListener('message', (event) => {
  // Always verify the origin
  if (event.origin !== CADIT_ORIGIN) return;

  const { type, payload } = event.data;

  switch (type) {
    case 'ready':
      console.log('CADit is ready!', payload.version);
      // Initialize with your partner name
      caditFrame.contentWindow.postMessage({
        type: 'init',
        payload: { partnerName: 'YourApp', features: ['export'] }
      }, CADIT_ORIGIN);
      break;

    case 'export-stl':
      // User clicked "Send to YourApp" or you requested an export
      const { blob, filename } = payload;
      console.log(`Received ${filename} (${blob.size} bytes)`);
      break;

    case 'cadit-auth-request':
      // Handle partner auth (see Authentication section)
      break;
  }
});

3. Request an STL export

caditFrame.contentWindow.postMessage(
  { type: 'get-stl' },
  CADIT_ORIGIN
);

That's it — three steps to embed a full 3D editor with STL export.

Live Demo

Visit cookiecad.github.io/cadit-embed-example to see a working integration.

Features

  • 3D Editor — Full CADit editor embedded in an iframe with 2D sketch + 3D modeling tools
  • STL Export — Request STL files programmatically or let users click "Send to [YourApp]"
  • STL Import — Send STL files into CADit for editing
  • Partner Authentication — Signed JWT handshake for seamless single sign-on
  • Account Linking — Users link their partner account to CADit once, then sign in silently
  • Custom Branding — The export button reads "Send to [YourApp]" automatically

Screenshots

CADit Editor in Embed Mode

The editor shows your partner name in the "Send to" button:

CADit editor showing "Send to MyApp" button

STL Export Controls

Request and download STL exports from your host page:

STL export controls

Auth Controls

The auth handshake happens automatically via postMessage:

Auth controls panel

Event Log

All postMessage communication is visible for debugging:

Event log showing auth message exchange

Message Protocol

All communication uses window.postMessage with this envelope:

interface EmbedMessage {
  type: string;
  payload?: Record<string, unknown>;
}

Inbound Messages (Your App → CADit)

Type Payload Description
init InitPayload Initialize the embed session with your partner name
get-stl none Request the current design as an STL file
import-stl ImportStlPayload Import an STL file into CADit for editing
partner-auth-token PartnerAuthTokenPayload Send a signed JWT in response to an auth request

Outbound Messages (CADit → Your App)

Type Payload Description
ready ReadyPayload CADit has loaded and is ready to receive messages
export-stl ExportStlPayload An STL file is being sent (user-initiated or requested)
cadit-auth-request AuthRequestPayload CADit is requesting a signed auth token

Payload Types

// Inbound payloads

interface InitPayload {
  partnerName: string;      // Displayed in the "Send to [name]" button
  features?: string[];      // Optional feature flags, e.g. ['export']
}

interface ImportStlPayload {
  blob: Blob | ArrayBuffer; // The STL file data
  filename?: string;        // Optional filename
}

interface PartnerAuthTokenPayload {
  token: string;            // Signed JWT (RS256)
  nonce: string;            // Echo of the nonce from cadit-auth-request
}

// Outbound payloads

interface ReadyPayload {
  version: string;          // CADit version
}

interface ExportStlPayload {
  blob: Blob;               // The STL file as a Blob
  filename: string;         // Suggested filename, e.g. "design.stl"
}

interface AuthRequestPayload {
  nonce: string;            // Random nonce — must be echoed back in the JWT
  version: string;          // Auth protocol version
}

Message Flow

Your App (parent)                   CADit (iframe)
      │                                   │
      │         ◄── ready ──────────────  │  CADit has loaded
      │                                   │
      │  ────── init ──────────────────►  │  Set partner name
      │                                   │
      │         ◄── cadit-auth-request ─  │  Auth nonce
      │                                   │
      │  ────── partner-auth-token ────►  │  Signed JWT
      │                                   │
      │         ◄── export-stl ─────────  │  User clicks "Send to YourApp"
      │                                   │
      │  ────── get-stl ───────────────►  │  Programmatic export request
      │         ◄── export-stl ─────────  │  STL response
      │                                   │

Authentication / Partner Auth

Partner auth lets users of your platform sign into CADit automatically when they use the embedded editor. It uses a signed RS256 JWT handshake over postMessage — no redirects or pop-ups for returning users. On first visit, users link their partner account to CADit once; after that, authentication is silent.

For full details — JWT claims, signing examples, token verification, and user flow screenshots — see the Authentication Guide.

URL Parameters

Append these query parameters to the CADit iframe URL:

Parameter Value Description
embed true Required. Enables embed mode (hides navigation, adjusts UI)
partnerName string Sets the partner name for the "Send to [name]" button. Can also be set via init message.

Example URL:

https://app.cadit.app/new?embed=true&partnerName=YourApp

Security

Origin Verification

All postMessage communication is origin-verified on both sides:

  • Your app must check event.origin matches the CADit origin before processing any message.
  • CADit only accepts messages from origins in its allowlist.
  • CADit never uses * as a target origin for outbound messages.
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.cadit.app') return;
  // Safe to process event.data
});

Allowed Origins

Your domain must be registered with CADit before the embed will work. This includes:

  • Production domains
  • Staging/preview domains
  • Local development origins (e.g. http://localhost:8080)
  • Any white-label or custom domains

Token Verification

Auth tokens are verified server-side by CADit:

  • RS256 signature is checked against your public key (via JWKS endpoint or static key)
  • iss, aud, exp, iat, and nonce are all validated
  • jti is checked for uniqueness to prevent replay attacks
  • Tokens must be short-lived (1-5 minutes)

Local Development

1. Clone and serve

git clone https://github.com/cookiecad/cadit-embed-example.git
cd cadit-embed-example

# Using Node.js
npx serve

# Or using Python
python -m http.server 8080

2. Configure the CADit origin

In script.js, set CADIT_ORIGIN to match your CADit instance:

// For local CADit development
const CADIT_ORIGIN = 'http://localhost:5173';

// For production
const CADIT_ORIGIN = 'https://app.cadit.app';

3. Ensure your origin is allowed

Your local development origin (e.g. http://localhost:3000) must be in CADit's allowed origins list. Contact the CADit team to add it.

4. Open in browser

Navigate to http://localhost:3000 (or whichever port your server is using). You should see the CADit editor load in the iframe with the "Send to" button showing your partner name.

Getting Started as a Partner

To integrate CADit into your application, send us the following:

Item Description Example
Issuer Your iss claim value https://yourapp.com
Public Key JWKS endpoint URL or a static public key (PEM/JWK) https://yourapp.com/.well-known/jwks.json
Audience Your preferred aud claim value for CADit https://cookiecad.com
Allowed Origins All domains that will host the CADit iframe https://yourapp.com, https://app.yourapp.com
Signing Algorithm Currently only RS256 is supported RS256
Token Claims Confirm which claims you'll include sub, email, email_verified
Test Environment Staging URLs and test credentials (if applicable) https://staging.yourapp.com

Contact us at the CADit website or open an issue on this repo.

API Reference

Messages: Your App → CADit

Message Type Payload When to Send
init { partnerName: string, features?: string[] } After receiving ready
get-stl none When you want the current design as STL
import-stl { blob: Blob | ArrayBuffer, filename?: string } To load an STL into the editor
partner-auth-token { token: string, nonce: string } In response to cadit-auth-request

Messages: CADit → Your App

Message Type Payload When Sent
ready { version: string } Once on iframe load
export-stl { blob: Blob, filename: string } On "Send to [Partner]" click or get-stl response
cadit-auth-request { nonce: string, version: string } When CADit needs the user authenticated

URL Parameters

Parameter Required Description
embed=true Yes Enables embed mode
partnerName=YourApp No Sets partner display name (also settable via init)

License

MIT