@makemind/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to `@makemind/sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0
+
+First release. The public surface is not frozen: while this package is 0.x, a minor bump may change it.
+
+### Added
+
+### Corrected before first release
+
+- `FlowListItem` described six fields while `GET /logic/flows` returns
+  eighteen, so consumers cast the row to read `publicExecution` or `mode`. It
+  now describes the payload.
+- `FlowListItem.status` declared `'active'`, a value the route never sends: a
+  published flow is stored and returned as `'published'`.
+- `ComponentNode` omitted `dataBinding`, `validation`, `a11y` and
+  `conditions.className`. A consumer building a node from this type could not
+  express a data binding at all. Kept in step with the App Builder's own
+  declaration by `component-node-parity.test.ts`.
+- `listFlows()` took no arguments and returned a bare array. It now accepts
+  `status`, `mode`, `limit` and `cursor` — the gateway has always supported
+  them — and returns `{ flows, hasMore, nextCursor }`, so a truncated page is
+  distinguishable from a complete one.
+
+- `initializeMAKEMIND()` / `getMAKEMIND()` entry points for configuring the SDK
+  with an API key, application ID, environment, and optional gateway `baseUrl`
+  override.
+- Optional Firebase App Check integration (`getAppCheckToken`) attached as the
+  `X-Firebase-AppCheck` header on every gateway call.
+- Eleven typed platform services, each a thin client over the MAKEMIND API
+  gateway:
+  - `auth` — email/password sign-in and sign-up, auth state subscription,
+    tenant memberships, tenant switching, sign-out.
+  - `data` — tenant-isolated document query/get/create/update and real-time
+    collection subscriptions.
+  - `logic` — workflow transitions (ECO, NCR, marketplace bid, gate approval)
+    and generic flow execution.
+  - `tenant` — tenant profile, settings, members, invitations, and
+    workspaces.
+  - `messaging` — notification send, real-time notification subscription,
+    and mark-as-read.
+  - `settlement` — usage-event recording, usage stats, billing summary,
+    quota status, and invoices.
+  - `storage` — file upload/download, metadata, listing, copy/move/delete,
+    PLM document helpers, and bucket management.
+  - `ai` — chat completion (including streaming and tool calling),
+    embeddings, vector search, vision analysis, and text
+    generate/summarize/translate helpers.
+  - `search` — full-text query, advanced faceted search, autocomplete
+    suggestions, analytics, and bulk reindexing.
+  - `apps` — App Builder app/page CRUD, publishing and versioning, domain
+    management, AI-assisted UI generation, and live-edit collaboration
+    sessions.
+  - `marketplace` — listing discovery/search, install/uninstall, app
+    runtime proxying, reviews, and the publisher/admin publishing
+    lifecycle.
+- `call(operation, input)` generic RPC dispatch for platform Callable
+  operations that do not yet have a dedicated typed service method.
+- `MAKEMINDError` / `ErrorCodes` for structured error handling across all
+  services.
+- `firebase` as an **optional** peer dependency. It is loaded on demand by the
+  push-notification methods and by App Check token retrieval; the SDK imports
+  and every gateway call work with `firebase` absent.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MAKEMIND
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,550 @@
+# @makemind/sdk
+
+MAKEMIND Platform SDK for Web Applications (React, Vue, Angular, etc.)
+
+## Installation
+
+```bash
+npm install @makemind/sdk
+```
+
+The SDK talks to the MAKEMIND API gateway over HTTPS. Installing it pulls in
+nothing else: you only need an API key and your application ID.
+
+`firebase` is an **optional** peer. Two features load it on demand and only
+when you use them — web push (`messaging.registerDevice`,
+`messaging.onPushMessage`) and App Check tokens. Everything else, including
+every gateway call, works with `firebase` absent.
+
+## Quick Start
+
+```typescript
+import { initializeMAKEMIND, getMAKEMIND } from '@makemind/sdk';
+
+// Initialize MAKEMIND SDK
+initializeMAKEMIND({
+  apiKey: 'your-api-key',
+  applicationId: 'plm', // Your application ID
+  environment: 'development',
+  // Optional: override the gateway base URL (defaults to https://api.makemind.app).
+  // Point this at a locally running gateway during development.
+  baseUrl: 'http://127.0.0.1:5001/<project-id>/us-central1/apiGateway',
+});
+
+// Use the SDK
+const makemind = getMAKEMIND();
+```
+
+`initializeMAKEMIND` accepts `{ apiKey, applicationId, environment?, baseUrl?, apiVersion?, getAppCheckToken? }`.
+All service calls are issued against `${baseUrl}/api/${apiVersion}` (`apiVersion`
+defaults to `v1`).
+
+### App Check (first-party apps only)
+
+Pass `getAppCheckToken` — an async provider returning a Firebase App Check
+token — to have the SDK attach it as `X-Firebase-AppCheck` on every gateway
+call. This lets browser/mobile apps pass App Check enforcement on the pre-login
+endpoints (signin/signup/password-reset/oauth). Backward-compatible: omit it for
+M2M / API-key integrations (exempt from App Check server-side), and a provider
+returning `null` simply omits the header.
+
+```typescript
+import { getToken } from 'firebase/app-check';
+initializeMAKEMIND({
+  apiKey, applicationId,
+  getAppCheckToken: async () => (await getToken(appCheck, false)).token,
+});
+```
+
+## Authentication
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Sign in with email + password
+const user = await makemind.auth.signInWithEmail(email, password);
+
+// Sign up a new user
+const newUser = await makemind.auth.signUp(email, password, {
+  displayName: 'Jane Doe',
+});
+
+// Listen to auth state changes
+const unsubscribe = makemind.auth.onAuthStateChanged((user) => {
+  if (user) {
+    console.log('User signed in:', user.uid);
+    console.log('Tenant:', user.tenantId);
+    console.log('Roles:', user.roles);
+  }
+});
+
+// Sign out
+await makemind.auth.signOut();
+
+// Get user memberships (tenants user belongs to)
+const memberships = await makemind.auth.getUserMemberships();
+
+// Switch tenant
+await makemind.auth.switchTenant('new-tenant-id');
+```
+
+## Data Operations
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Query with tenant isolation
+const { data: products } = await makemind.data.query({
+  collection: 'plm_products',
+  where: [
+    { field: 'tenant_id', op: '==', value: makemind.tenantId },
+    { field: 'status', op: '==', value: 'active' },
+  ],
+  orderBy: [{ field: 'created_at', direction: 'desc' }],
+  limit: 20,
+});
+
+// Get single document
+const product = await makemind.data.get({
+  collection: 'plm_products',
+  documentId: 'product-id',
+});
+
+// Create document (tenant_id auto-added)
+const result = await makemind.data.create({
+  collection: 'plm_products',
+  data: {
+    product_code: 'PRD-001',
+    product_name: 'Sample Product',
+    status: 'development',
+  },
+});
+
+// Update document
+await makemind.data.update({
+  collection: 'plm_products',
+  documentId: 'product-id',
+  data: { status: 'active' },
+});
+
+// Real-time subscription
+const unsubscribe = makemind.data.onCollectionSnapshot(
+  {
+    collection: 'plm_products',
+    where: [{ field: 'tenant_id', op: '==', value: makemind.tenantId }],
+  },
+  (products) => {
+    console.log('Products updated:', products);
+  }
+);
+
+// Cleanup
+unsubscribe();
+```
+
+## Logic / Workflows
+
+```typescript
+const makemind = getMAKEMIND();
+
+// ECO workflow transition
+await makemind.logic.ecoTransition('eco-id', 'submit');
+await makemind.logic.ecoTransition('eco-id', 'approve', {
+  comments: 'Approved for implementation',
+});
+
+// NCR workflow
+await makemind.logic.ncrTransition('issue-id', 'assignContainment', {
+  assignedTo: 'user-id',
+  containmentAction: 'Quarantine affected parts',
+});
+
+// Marketplace bid
+await makemind.logic.bidTransition('request-id', 'bid-id', 'submit');
+
+// Gate approval
+await makemind.logic.gateApproval('product-id', 'production', 'approve');
+
+// Generic flow execution
+const result = await makemind.logic.executeFlow('flow-id', {
+  input: 'data',
+});
+```
+
+## Tenant Management
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Get current tenant
+const tenant = await makemind.tenant.getCurrent();
+
+// Update tenant settings
+await makemind.tenant.updateTenant({
+  settings: { industryType: 'electronics' },
+});
+
+// List members
+const members = await makemind.tenant.listMembers();
+
+// Invite member
+await makemind.tenant.inviteMember({
+  email: 'new@example.com',
+  role: 'manager',
+});
+
+// Workspaces
+const workspaces = await makemind.tenant.listWorkspaces();
+await makemind.tenant.createWorkspace({
+  name: 'Development Team',
+  description: 'R&D workspace',
+});
+```
+
+## Messaging / Notifications
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Send notification
+await makemind.messaging.send({
+  template: 'ecoReviewRequest',
+  recipients: ['user-1', 'user-2'],
+  data: {
+    ecoNumber: 'ECO-2024-001',
+    title: 'Design Change Request',
+  },
+  channels: ['push', 'email'],
+});
+
+// Listen to notifications
+const unsubscribe = makemind.messaging.onNotifications(
+  (notifications) => {
+    console.log('Notifications:', notifications);
+  },
+  { unreadOnly: true }
+);
+
+// Mark as read
+await makemind.messaging.markAsRead('notification-id');
+```
+
+## Settlement / Billing
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Record usage event
+await makemind.settlement.recordProductCreation('product-id');
+await makemind.settlement.recordDocumentUpload('doc-id', 2.5); // 2.5 MB
+
+// Get usage stats
+const stats = await makemind.settlement.getUsageStats('currentMonth');
+
+// Get billing summary
+const billing = await makemind.settlement.getBillingSummary();
+
+// Check quotas
+const quotas = await makemind.settlement.getQuotaStatus();
+
+// List invoices
+const invoices = await makemind.settlement.listInvoices({ status: 'pending' });
+```
+
+## Storage
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Upload a file
+const uploaded = await makemind.storage.upload({
+  path: 'products/product-id/documents/spec.pdf',
+  file: fileFromInput, // File | Blob
+  metadata: { documentType: 'spec' },
+  onProgress: (progress) => console.log(`${progress.toFixed(0)}%`),
+});
+
+// Get a download URL / download directly
+const url = await makemind.storage.getDownloadUrl('products/product-id/documents/spec.pdf');
+const blob = await makemind.storage.download('products/product-id/documents/spec.pdf');
+
+// List, copy, move, delete
+const { files } = await makemind.storage.listFiles({ prefix: 'products/product-id/documents/' });
+await makemind.storage.copy('a.pdf', 'b.pdf');
+await makemind.storage.move('a.pdf', 'archive/a.pdf');
+await makemind.storage.delete('a.pdf');
+
+// PLM-specific helpers
+await makemind.storage.uploadProductDocument('product-id', file, { documentType: 'drawing' });
+await makemind.storage.uploadEcoAttachment('eco-id', file);
+await makemind.storage.uploadQualityAttachment('issue-id', file);
+const productDocs = await makemind.storage.getProductDocuments('product-id');
+
+// Bucket management
+const buckets = await makemind.storage.listBuckets();
+await makemind.storage.createBucket({ name: 'reports', publicAccess: false });
+const stats = await makemind.storage.getUsageStats();
+```
+
+## AI
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Chat completion
+const { message, usage } = await makemind.ai.chat([
+  { role: 'user', content: 'Summarize this ECO for a release note.' },
+]);
+
+// Streaming (polling-based; delivers content deltas as they arrive)
+await makemind.ai.chatStream(
+  [{ role: 'user', content: 'Draft a quality report.' }],
+  (chunk) => process.stdout.write(chunk),
+  { onDone: (response) => console.log('done', response.usage) }
+);
+
+// Or consume as an async generator
+for await (const delta of makemind.ai.streamChat([{ role: 'user', content: 'Hi' }])) {
+  console.log(delta);
+}
+
+// Embeddings
+const { embeddings } = await makemind.ai.createEmbedding(['spec text', 'another doc']);
+
+// Vector search over a tenant knowledge collection
+const hits = await makemind.ai.vectorSearch('specs', 'torque tolerance', { limit: 5 });
+
+// Vision
+await makemind.ai.analyzeImage('https://example.com/part.png', 'Describe this part.');
+await makemind.ai.analyzeImageBase64(base64Data, 'image/png', 'Describe this part.');
+
+// Tool calling
+const { toolCalls } = await makemind.ai.chatWithTools(
+  [{ role: 'user', content: 'Look up product PRD-001.' }],
+  [{ name: 'getProduct', description: 'Fetch a product by code', parameters: { type: 'object' } }]
+);
+
+// Convenience helpers
+const { text } = await makemind.ai.generate('Write a one-line changelog entry.');
+const { summary } = await makemind.ai.summarize(longText, { style: 'bullet', maxLength: 100 });
+const { translation } = await makemind.ai.translate('Hello world', 'ko');
+```
+
+## Search
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Simple query
+const results = await makemind.search.query({ q: 'bracket', collections: ['plm_products'], perPage: 20 });
+
+// Advanced query with facets/filters/highlighting
+const advanced = await makemind.search.advanced({
+  query: 'bracket',
+  collection: 'plm_products',
+  facets: ['status', 'category'],
+  filters: { status: 'active' },
+  highlightFields: ['product_name'],
+});
+
+// Autocomplete suggestions
+const suggestions = await makemind.search.suggestions({ prefix: 'brac', collection: 'plm_products' });
+
+// Analytics and reindexing
+const analytics = await makemind.search.getAnalytics({ startDate: '2026-01-01' });
+const { jobId } = await makemind.search.bulkReindex({ collection: 'plm_products' });
+const status = await makemind.search.getBulkReindexStatus({ jobId });
+```
+
+## Apps (App Builder)
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Create and manage apps
+const { appId } = await makemind.apps.createApp({ name: 'field-service', displayName: 'Field Service' });
+const app = await makemind.apps.getApp(appId);
+const { apps } = await makemind.apps.listApps({ status: 'draft' });
+await makemind.apps.updateApp(appId, { settings: { theme: { mode: 'dark' } } });
+
+// Pages
+const { pageId } = await makemind.apps.createPage(appId, { name: 'Home', path: '/', isHomePage: true });
+await makemind.apps.updatePage(appId, pageId, { title: 'Home' });
+const pages = await makemind.apps.listPages(appId);
+
+// Publishing & versioning
+await makemind.apps.publish(appId, 'Initial release');
+const versions = await makemind.apps.getVersions(appId);
+await makemind.apps.rollback(appId, versions[0].version);
+
+// Domains
+await makemind.apps.addSubdomain(appId, 'field-service');
+const { verificationToken, dnsRecords } = await makemind.apps.addCustomDomain(appId, 'app.example.com');
+
+// AI-assisted UI generation
+const { components } = await makemind.apps.generateUI('A form to log a quality issue');
+
+// Live-edit collaboration
+const { sessionToken, wsEndpoint } = await makemind.apps.startSession(appId, pageId);
+```
+
+## Marketplace
+
+```typescript
+const makemind = getMAKEMIND();
+
+// Discovery
+const results = await makemind.marketplace.search({ query: 'inventory', category: 'operations' });
+const listing = await makemind.marketplace.getDetail('listing-id');
+const featured = await makemind.marketplace.getFeatured();
+
+// Installation
+const { bindingId } = await makemind.marketplace.install('listing-id');
+const installed = await makemind.marketplace.listInstalled();
+await makemind.marketplace.uninstall('listing-id');
+
+// App runtime (proxy calls through the installed binding)
+const config = await makemind.marketplace.getConfig(bindingId);
+await makemind.marketplace.proxy(bindingId, { method: 'GET', path: 'items' });
+
+// Reviews
+await makemind.marketplace.createReview({ listingId: 'listing-id', rating: 5, body: 'Great app' });
+const reviews = await makemind.marketplace.listReviews('listing-id');
+
+// Publishing (for publisher tenants)
+await makemind.marketplace.createPublisherProfile({
+  displayName: 'Acme Apps',
+  description: 'Field service tools',
+  logoUrl: 'https://example.com/logo.png',
+  supportEmail: 'support@acme.example',
+});
+const newListing = await makemind.marketplace.createListing({ name: 'Inventory Sync' });
+await makemind.marketplace.submitForReview((newListing as { listingId: string }).listingId);
+```
+
+## Platform Operations (Generic Dispatch)
+
+Every typed service method (`data.*`, `tenant.*`, `messaging.*`, ...) is a thin
+wrapper around the gateway's RPC dispatch route. When a backend operation does
+not yet have a typed service method, call it directly with `makemind.call()`:
+
+```typescript
+const makemind = getMAKEMIND();
+
+// call<T>(operation, input) -> POST /api/v<version>/call/:operation
+// The `{ data }` response envelope is already unwrapped.
+const result = await makemind.call('updateMyProfile', { displayName: 'Jane Doe' });
+```
+
+`call(operation, input)` invokes a platform Callable operation through the
+gateway RPC dispatch route. The operation key is the deployed Callable name:
+namespaced groups use `<prefix>-<name>` (e.g. `settlement-getMRR`,
+`marketplace-listPublisherListings`); flat exports use the bare name (e.g.
+`createTenant`, `updateMyProfile`). Each operation enforces its own
+authorization server-side (platform roles / tenant scopes), so calling an
+operation you are not authorized for still fails with `PERMISSION_DENIED` —
+`call()` does not bypass access control.
+
+This is distinct from `logic.call(functionName, input)`, which executes a
+tenant-defined *logic* function (`POST /logic/call`), not a platform Callable.
+
+Some illustrative operations reachable only through `call()` (no dedicated
+typed method yet):
+
+```typescript
+await makemind.call('platformGetAuditLogs', { limit: 50 });
+await makemind.call('updateMyProfile', { displayName: 'Jane Doe' });
+await makemind.call('endusers-listEndUsers', { limit: 20 });
+await makemind.call('knowledge-knowledgeCreateUploadUrl', { fileName: 'spec.pdf' });
+await makemind.call('getBillingContact', {});
+await makemind.call('updateBillingContact', { email: 'billing@example.com' });
+await makemind.call('getMyLoginHistory', { limit: 10 });
+await makemind.call('createBrandingLogoUploadUrl', { fileName: 'logo.png' });
+await makemind.call('marketplace-listPublisherListings', {});
+```
+
+## React Integration Example
+
+```tsx
+// src/lib/makemind.ts
+import { initializeMAKEMIND } from '@makemind/sdk';
+
+export const makemind = initializeMAKEMIND({
+  apiKey: import.meta.env.VITE_MAKEMIND_API_KEY,
+  applicationId: 'plm',
+  environment: import.meta.env.DEV ? 'development' : 'production',
+  baseUrl: import.meta.env.VITE_MAKEMIND_BASE_URL, // optional gateway override
+});
+
+// src/hooks/useProducts.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+import { getMAKEMIND } from '@makemind/sdk';
+
+export function useProducts() {
+  const makemind = getMAKEMIND();
+
+  return useQuery({
+    queryKey: ['plm_products', makemind.tenantId],
+    queryFn: async () => {
+      const result = await makemind.data.query({
+        collection: 'plm_products',
+        where: [
+          { field: 'tenant_id', op: '==', value: makemind.tenantId! },
+        ],
+        orderBy: [{ field: 'updated_at', direction: 'desc' }],
+      });
+      return result.data;
+    },
+    enabled: !!makemind.tenantId,
+  });
+}
+
+export function useCreateProduct() {
+  const queryClient = useQueryClient();
+  const makemind = getMAKEMIND();
+
+  return useMutation({
+    mutationFn: async (data: CreateProductInput) => {
+      const result = await makemind.data.create({
+        collection: 'plm_products',
+        data,
+      });
+
+      // Record usage
+      await makemind.settlement.recordProductCreation(result.id);
+
+      return result;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['plm_products'] });
+    },
+  });
+}
+```
+
+## Error Handling
+
+```typescript
+import { MAKEMINDError, ErrorCodes } from '@makemind/sdk';
+
+try {
+  await makemind.data.create({ ... });
+} catch (error) {
+  if (error instanceof MAKEMINDError) {
+    switch (error.code) {
+      case ErrorCodes.PERMISSION_DENIED:
+        console.error('Access denied');
+        break;
+      case ErrorCodes.QUOTA_EXCEEDED:
+        console.error('Quota exceeded');
+        break;
+      default:
+        console.error('Error:', error.message);
+    }
+  }
+}
+```
+
+## License
+
+MIT