@chatarmin/os 1.0.0 → 1.0.2

package/README.md

@@ -1,167 +1,837 @@
-# @chatarmin/os-sdk
+# @chatarmin/os
 
-Type-safe SDK for ChatarminOS - Customer & Subscription Management.
+> Type-safe SDK for ChatarminOS — the all-in-one platform for B2B SaaS to manage customers, subscriptions, feature access, and billing.
 
-## Installation
+[![npm version](https://img.shields.io/npm/v/@chatarmin/os.svg)](https://www.npmjs.com/package/@chatarmin/os)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-> **Note**: This is a private npm package. You need authentication to install it.
+## Features
 
-### 1. Configure npm Authentication
+- 🏢 **Company Management** — Create, link, and manage customer companies
+- 🎫 **Subscription Tiers** — Define tiers with features and Stripe pricing
+- ✨ **Feature Access** — Check entitlements and enforce usage limits
+- 📊 **Usage Tracking** — Metered billing with idempotency support
+- 💳 **Stripe Integration** — Claim checkout sessions, link subscriptions
+- 🔗 **Smart Linking** — Intelligent company matching by domain/name/email
+- 👥 **Contact Sync** — Bulk upsert contacts for each company
+- 🚀 **Unified Onboarding** — Complete setup in a single API call
 
-Create a `.npmrc` file in your project root:
+---
 
-```bash
-# .npmrc
-@chatarmin:registry=https://registry.npmjs.org/
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
-```
+## Table of Contents
 
-Set your npm token as an environment variable:
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [Companies](#companies)
+  - [Contacts](#contacts)
+  - [Features](#features)
+  - [Billing](#billing)
+  - [Subscriptions & Tiers](#subscriptions--tiers)
+  - [Links](#links)
+  - [Onboarding](#onboarding)
+- [Common Patterns](#common-patterns)
+- [TypeScript Support](#typescript-support)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
 
-```bash
-# .env (for local development)
-NPM_TOKEN=npm_yourtokenhere
+---
 
-# Or export it in your shell
-export NPM_TOKEN=npm_yourtokenhere
-```
-
-**For CI/CD**: Add `NPM_TOKEN` as a secret in your deployment platform (GitHub Actions, Vercel, etc.)
-
-### 2. Install the Package
+## Installation
 
 ```bash
-npm install @chatarmin/os-sdk
+pnpm add @chatarmin/os
 # or
-pnpm add @chatarmin/os-sdk
+npm install @chatarmin/os
 # or
-yarn add @chatarmin/os-sdk
+yarn add @chatarmin/os
 ```
 
-> See [PUBLISHING.md](./PUBLISHING.md) for detailed setup instructions.
+---
 
 ## Quick Start
 
 ```typescript
-import { ChatarminOS } from "@chatarmin/os-sdk"
+import { ChatarminOS } from "@chatarmin/os"
 
 const os = new ChatarminOS({
-  apiKey: process.env.CHATARMIN_OS_API_KEY!,
+  apiKey: process.env.OS_API_KEY!,
   // Optional: custom base URL for self-hosted
   // baseUrl: 'https://your-os.example.com/api/v1'
 })
+
+// Onboard a new customer (single call does everything!)
+const result = await os.onboard({
+  externalOrgId: "org_abc123", // Your product's org ID
+  hints: {
+    companyName: "Acme Inc",
+    domain: "acme.com",
+  },
+  tierCode: "free",
+  contactEmail: "admin@acme.com",
+  contactName: "John Doe",
+})
+
+console.log(result.companyId) // Use this for all future API calls
+console.log(result.linkStatus) // 'created' | 'linked' | 'already_linked'
 ```
 
-## Usage
+---
+
+## API Reference
 
 ### Companies
 
+Manage customer companies and their links to your product.
+
+#### `companies.getByProductLink(input)`
+
+Look up a company by your external organization ID.
+
 ```typescript
-// Find company by your external org ID
 const company = await os.companies.getByProductLink({
-  externalOrgId: "org_123",
+  externalOrgId: "org_abc123",
 })
 
-// Create a new company and link to your product
-const newCompany = await os.companies.create({
+if (company) {
+  console.log(`Found: ${company.name} (${company.id})`)
+} else {
+  console.log("Company not linked yet")
+}
+```
+
+#### `companies.create(input)`
+
+Create a new company and link it to your product.
+
+```typescript
+const company = await os.companies.create({
   name: "Acme Inc",
   domain: "acme.com",
-  externalOrgId: "org_456",
-  contactEmail: "billing@acme.com",
+  externalOrgId: "org_abc123",
+  contactEmail: "admin@acme.com",
   contactName: "John Doe",
+  createdAt: "2024-01-15T10:30:00.000Z", // Optional: historical date
+})
+
+console.log(company.id) // UUID
+console.log(company.shortId) // e.g., "acme-inc"
+```
+
+#### `companies.update(input)`
+
+Update company metadata (e.g., backfill historical dates).
+
+```typescript
+await os.companies.update({
+  companyId: "uuid-here",
+  createdAt: "2023-06-01T00:00:00.000Z",
 })
+```
+
+#### `companies.smartLink(input)`
 
-// Smart link - find existing company by hints
-const linked = await os.companies.smartLink({
-  externalOrgId: "org_789",
+Intelligently find and link a company using hints.
+
+```typescript
+const result = await os.companies.smartLink({
+  externalOrgId: "org_abc123",
   hints: {
-    companyName: "Acme",
+    companyName: "Acme Inc",
     domain: "acme.com",
     emails: ["john@acme.com", "jane@acme.com"],
   },
-  minConfidence: 0.8,
+  minConfidence: 0.7, // Default: 0.6
 })
+
+switch (result.status) {
+  case "already_linked":
+    console.log("Already linked to your product")
+    break
+  case "linked":
+    console.log(
+      `Auto-linked to ${result.customerName} (${result.confidence}% confidence)`
+    )
+    break
+  case "suggestions":
+    console.log("Multiple matches found:", result.suggestions)
+    break
+  case "no_match":
+    console.log("No matching company found")
+    break
+}
 ```
 
-### Subscriptions & Tiers
+**Matching priority:**
+
+1. Domain match → 95% confidence
+2. Name match → up to 80% confidence
+3. Email domain match → 70% confidence
+
+---
+
+### Contacts
+
+Manage people associated with companies.
+
+#### `contacts.create(input)`
+
+Create or update a single contact.
 
 ```typescript
-// Apply a subscription tier to a company
-await os.subscriptions.create("pro", {
-  companyId: company.id,
+const contact = await os.contacts.create({
+  companyId: "comp_xxx",
+  email: "john@acme.com",
+  name: "John Doe",
+  role: "CEO",
+  isPrimary: true,
+  avatarUrl: "https://example.com/avatar.jpg",
+  metadata: { slackId: "U123" },
 })
 
-// With feature overrides
-await os.subscriptions.create("enterprise", {
-  companyId: company.id,
-  features: {
-    ai_credits: { included_quantity: 1000 },
-  },
+if (contact.isNew) {
+  console.log("Created new contact")
+} else {
+  console.log("Updated existing contact")
+}
+```
+
+#### `contacts.bulkUpsert(input)`
+
+Bulk create or update multiple contacts. **Recommended for onboarding.**
+
+```typescript
+const result = await os.contacts.bulkUpsert({
+  companyId: "comp_xxx",
+  contacts: [
+    { email: "ceo@acme.com", name: "Alice", role: "CEO", isPrimary: true },
+    { email: "cto@acme.com", name: "Bob", role: "CTO" },
+    { email: "dev@acme.com", name: "Charlie", role: "Engineer" },
+  ],
 })
 
-// List available tiers
-const tiers = await os.tiers.list()
+console.log(`Created: ${result.created}, Updated: ${result.updated}`)
+// result.contacts contains individual results with IDs
+```
+
+#### `contacts.list(companyId, primaryOnly?)`
 
-// Get tier details
-const proTier = await os.tiers.get("pro")
+List contacts for a company.
+
+```typescript
+// Get all contacts
+const contacts = await os.contacts.list("comp_xxx")
+
+// Get only the primary contact
+const [primary] = await os.contacts.list("comp_xxx", true)
 ```
 
-### Feature Access
+---
+
+### Features
+
+Check and manage feature access for companies.
+
+#### `features.check(input)`
+
+Check if a company has access to a specific feature.
 
 ```typescript
-// Check if company has access to a feature
 const access = await os.features.check({
-  companyId: company.id,
-  featureCode: "whatsapp_messages",
+  companyId: "comp_xxx",
+  featureCode: "ai_credit",
 })
 
-if (access.hasAccess) {
-  console.log(`Limit: ${access.limit}, Used: ${access.currentUsage}`)
+console.log({
+  enabled: access.isEnabled, // Feature is turned on
+  canUse: access.canUse, // Can use right now (not at limit)
+  hasQuantity: access.hasQuantity, // Is a quantity-based feature
+  usage: access.currentUsage, // Current usage count
+  limit: access.quantityLimit, // Max allowed (null = unlimited)
+  included: access.includedQuantity, // Free tier before billing
+  remaining: access.remaining, // How many left (null = unlimited)
+})
+
+if (!access.canUse) {
+  throw new Error("Upgrade required")
 }
+```
+
+#### `features.listAccess(companyId)`
+
+List all features and their access status for a company.
 
-// List all feature access for a company
-const allAccess = await os.features.listAccess(company.id)
+```typescript
+const features = await os.features.listAccess("comp_xxx")
+
+for (const f of features) {
+  console.log(`${f.featureName}: ${f.isEnabled ? "✓" : "✗"}`)
+  if (f.quantityLimit) {
+    console.log(`  Usage: ${f.currentUsage} / ${f.quantityLimit}`)
+  }
+}
 ```
 
-### Billing & Usage Tracking
+#### `features.setAccess(input)`
+
+Update feature access with **partial config merge**.
 
 ```typescript
-// Track usage for a feature
-await os.billing.trackUsage({
-  companyId: company.id,
-  featureCode: "ai_credits",
+// Update by company ID
+await os.features.setAccess({
+  companyId: "comp_xxx",
+  featureCode: "ai_credit",
+  isEnabled: true,
+  quantityLimit: 1000,
+  includedQuantity: 100,
+  config: {
+    model: "gpt-4",
+    maxTokens: 4096,
+  },
+  source: "manual", // 'subscription' | 'manual' | 'trial' | 'api'
+  validUntil: new Date("2025-12-31"), // null for no expiration
+})
+
+// Update by external org ID
+await os.features.setAccess({
+  externalOrgId: "org_abc123",
+  featureCode: "team_seats",
+  config: { maxSeats: 50 }, // Only updates maxSeats, preserves other config
+})
+```
+
+#### `features.getAccessByExternalOrgId(externalOrgId)`
+
+Get all features using your product's external org ID.
+
+```typescript
+const result = await os.features.getAccessByExternalOrgId("org_abc123")
+
+console.log(`Company: ${result.companyId}`)
+for (const f of result.features) {
+  console.log(`${f.featureCode}: ${f.isEnabled}`)
+  console.log("  Config:", f.configValues)
+}
+```
+
+#### `features.checkByExternalOrgId(externalOrgId, featureCode)`
+
+Check a specific feature using your external org ID.
+
+```typescript
+const access = await os.features.checkByExternalOrgId("org_abc123", "ai_credit")
+
+if (access.canUse) {
+  console.log(`Remaining: ${access.remaining}`)
+}
+```
+
+---
+
+### Billing
+
+Track usage, claim subscriptions, and manage billing.
+
+#### `billing.trackUsage(input)`
+
+Track usage for a metered feature.
+
+```typescript
+const result = await os.billing.trackUsage({
+  companyId: "comp_xxx",
+  featureCode: "ai_credit",
   quantity: 5,
-  idempotencyKey: "unique-request-id", // Optional, for deduplication
-  metadata: { model: "gpt-4" }, // Optional
+  idempotencyKey: `request_${requestId}`, // Prevents double-counting
+  metadata: { model: "gpt-4", tokens: 1500 },
+})
+
+console.log({
+  currentUsage: result.currentUsage,
+  remaining: result.remaining,
+  billable: result.billableQuantity, // Amount beyond included tier
+  isAtLimit: result.isAtLimit,
 })
 ```
 
-### Manual Linking
+#### `billing.claimCheckout(input)`
+
+Claim a subscription from a completed Stripe Checkout Session.
+
+```typescript
+// In your Stripe checkout success handler
+const result = await os.billing.claimCheckout({
+  companyId: "comp_xxx",
+  checkoutSessionId: "cs_test_xxx", // From Stripe callback
+})
+
+if (result.alreadyClaimed) {
+  console.log("Subscription was already claimed")
+} else {
+  console.log(`Claimed subscription: ${result.subscriptionId}`)
+}
+```
+
+#### `billing.linkSubscription(input)`
+
+Link an existing Stripe subscription to a company.
+
+```typescript
+// When you create subscriptions on YOUR Stripe account
+const result = await os.billing.linkSubscription({
+  companyId: "comp_xxx",
+  stripeSubscriptionId: "sub_xxx",
+  stripeCustomerId: "cus_xxx", // Optional: fetched from subscription if omitted
+  tierCode: "pro", // Apply tier features
+  displayName: "Pro Plan",
+})
+
+console.log({
+  subscriptionId: result.subscriptionId,
+  isNew: !result.alreadyLinked,
+  featuresApplied: result.featuresApplied,
+})
+```
+
+#### `billing.getStatus(companyId)`
+
+Get billing status overview for a company.
+
+```typescript
+const status = await os.billing.getStatus("comp_xxx")
+
+console.log({
+  hasBilling: status.hasBillingProfile,
+  subscriptions: status.activeSubscriptions.length,
+  features: status.enabledFeaturesCount,
+})
+
+// Check active tier
+if (status.activeSubscriptions[0]?.tier) {
+  console.log(`Current tier: ${status.activeSubscriptions[0].tier.name}`)
+}
+```
+
+---
+
+### Subscriptions & Tiers
+
+Manage subscription tiers and apply features.
+
+#### `tiers.list()`
+
+List all available tiers for your product.
+
+```typescript
+const tiers = await os.tiers.list()
+
+for (const tier of tiers) {
+  console.log(`${tier.name} (${tier.code})`)
+}
+// ['Free', 'Pro', 'Enterprise']
+```
+
+#### `tiers.get(tierCode)`
+
+Get detailed tier information including Stripe prices.
+
+```typescript
+const tier = await os.tiers.get("pro")
+
+// Check base fee
+if (tier.baseFee) {
+  console.log(`Base fee: ${tier.baseFee.stripe.unitAmount / 100}€/mo`)
+  console.log(`Price ID: ${tier.baseFee.stripe.priceId}`)
+}
+
+// Access features
+for (const feature of tier.features) {
+  console.log(`${feature.code}:`, feature.configValues)
+}
+
+// Get all Stripe price IDs (base fee + feature prices)
+console.log("Stripe prices:", tier.stripePriceIds)
+// ['price_base', 'price_feature1', 'price_feature2']
+```
+
+#### `tiers.apply(tierCode, options)`
+
+Apply a tier's features to a company (without Stripe).
+
+```typescript
+// Apply free tier
+await os.tiers.apply("free", {
+  companyId: "comp_xxx",
+})
+
+// Apply with custom limits
+await os.tiers.apply("trial", {
+  companyId: "comp_xxx",
+  features: {
+    ai_credit: { included_quantity: 100 },
+    seats: { max_quantity: 10 },
+  },
+})
+```
+
+#### `subscriptions.create(tierCode, options)`
+
+Alias for `tiers.apply()` — apply a subscription tier.
+
+```typescript
+await os.subscriptions.create("pro", {
+  companyId: "comp_xxx",
+  features: {
+    ai_credit: { included_quantity: 500 },
+  },
+})
+```
+
+---
+
+### Links
+
+Manually manage product links.
+
+#### `links.create(input)`
+
+Create a manual link between your external org ID and an existing company.
 
 ```typescript
-// Link an external org ID to an existing company
 await os.links.create({
+  companyId: "comp_xxx",
+  externalOrgId: "org_abc123",
+  label: "Store Vienna", // Optional: display label
+  externalUserId: "user_xyz", // Optional: user who created the link
+})
+```
+
+#### `links.reset(options?)`
+
+Delete all product links for your product. Use before re-importing.
+
+```typescript
+// Basic reset (links only)
+const result = await os.links.reset()
+console.log(`Deleted ${result.linksDeleted} links`)
+
+// Full reset (links + contacts + MRR)
+const result = await os.links.reset({
+  deleteContacts: true,
+  resetMrr: true,
+})
+console.log(
+  `Deleted ${result.linksDeleted} links, ${result.contactsDeleted} contacts`
+)
+```
+
+---
+
+### Onboarding
+
+Complete customer onboarding in a single API call.
+
+The `onboard()` method handles:
+
+1. Smart company matching/creation
+2. Product linking
+3. Subscription claiming/linking
+4. Tier feature application
+
+#### Basic Usage
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123", // Your product's org ID (required)
+  hints: {
+    companyName: "Acme Inc",
+    domain: "acme.com",
+    emails: ["john@acme.com"],
+  },
+  tierCode: "free",
+  contactEmail: "admin@acme.com",
+  contactName: "John Doe",
+  createdAt: "2024-01-15T10:30:00.000Z", // Optional: historical date
+})
+
+console.log({
+  companyId: result.companyId,
+  companyName: result.companyName,
+  linkStatus: result.linkStatus, // 'created' | 'linked' | 'already_linked'
+  tierApplied: result.billingStatus?.tierApplied,
+})
+```
+
+#### Scenario 1: User Completed Stripe Checkout
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc", domain: "acme.com" },
+  checkoutSessionId: "cs_test_xxx", // From Stripe checkout callback
+})
+
+// result.billingStatus.claimed = true
+// result.billingStatus.subscriptionId = 'sub_xxx'
+```
+
+#### Scenario 2: Free Tier Signup
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc" },
+  tierCode: "free",
+  contactEmail: "admin@acme.com",
+})
+
+// result.billingStatus.tierApplied = true
+```
+
+#### Scenario 3: You Create Stripe Subscription
+
+```typescript
+// 1. Get tier prices
+const tier = await os.tiers.get("pro")
+
+// 2. Create subscription on YOUR Stripe account
+const stripeSub = await stripe.subscriptions.create({
+  customer: stripeCustomerId,
+  items: tier.stripePriceIds.map((price) => ({ price })),
+})
+
+// 3. Onboard with the subscription
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc" },
+  stripeSubscriptionId: stripeSub.id,
+  stripeCustomerId: stripeCustomerId,
+  tierCode: "pro",
+})
+
+// result.billingStatus.linked = true
+// result.billingStatus.tierApplied = true
+```
+
+#### Handling Existing Customers
+
+```typescript
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  hints: { companyName: "Acme Inc" },
+})
+
+switch (result.linkStatus) {
+  case "already_linked":
+    console.log("Welcome back!")
+    break
+  case "linked":
+    console.log("Found existing company, linked!")
+    break
+  case "created":
+    console.log("New company created!")
+    break
+}
+```
+
+---
+
+## Common Patterns
+
+### Feature Gating
+
+```typescript
+async function checkFeatureAccess(orgId: string, feature: string) {
+  const access = await os.features.checkByExternalOrgId(orgId, feature)
+
+  if (!access.isEnabled) {
+    throw new Error(`Feature ${feature} is not available on your plan`)
+  }
+
+  if (!access.canUse) {
+    throw new Error(`Usage limit reached for ${feature}. Please upgrade.`)
+  }
+
+  return access
+}
+
+// Usage
+await checkFeatureAccess("org_abc123", "ai_credit")
+await performAIOperation()
+await os.billing.trackUsage({
   companyId: company.id,
-  externalOrgId: "org_new_123",
-  externalUserId: "user_456", // Optional
+  featureCode: "ai_credit",
+  quantity: 1,
 })
 ```
 
-## Configuration
+### Stripe Subscription Flow
+
+```typescript
+// 1. User selects a plan → Get tier prices
+const tier = await os.tiers.get("pro")
+
+// 2. Create Stripe Checkout Session with tier prices
+const session = await stripe.checkout.sessions.create({
+  customer: customerId,
+  line_items: tier.stripePriceIds.map((price) => ({
+    price,
+    quantity: 1,
+  })),
+  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${baseUrl}/cancel`,
+})
+
+// 3. After checkout completes → Claim subscription
+const result = await os.onboard({
+  externalOrgId: "org_abc123",
+  checkoutSessionId: session.id,
+})
+```
 
-| Option    | Type     | Required | Default                           | Description                    |
-| --------- | -------- | -------- | --------------------------------- | ------------------------------ |
-| `apiKey`  | `string` | ✅       | -                                 | API key from ChatarminOS admin |
-| `baseUrl` | `string` | -        | `https://os.chatarmin.com/api/v1` | API endpoint                   |
+### Backfilling Historical Data
+
+```typescript
+import { ChatarminOS } from "@chatarmin/os"
+import historicalData from "./migration-data.json"
+
+const os = new ChatarminOS({ apiKey: process.env.OS_API_KEY! })
+
+for (const org of historicalData) {
+  // Create company with historical date
+  const result = await os.onboard({
+    externalOrgId: org.id,
+    hints: {
+      companyName: org.name,
+      domain: org.domain,
+    },
+    tierCode: org.plan,
+    contactEmail: org.adminEmail,
+    createdAt: org.createdAt, // Historical timestamp
+  })
+
+  // Sync contacts
+  await os.contacts.bulkUpsert({
+    companyId: result.companyId,
+    contacts: org.users.map((u) => ({
+      email: u.email,
+      name: u.name,
+      role: u.role,
+    })),
+  })
+}
+```
+
+---
 
 ## TypeScript Support
 
-The SDK is fully typed. All methods return properly typed responses based on the ChatarminOS API schema.
+The SDK is fully typed with comprehensive TypeScript definitions.
+
+### Importing Types
+
+```typescript
+import { ChatarminOS } from "@chatarmin/os"
+import type {
+  ChatarminOSConfig,
+  CreateCompanyInput,
+  SmartLinkInput,
+  SmartLinkResult,
+  ContactInput,
+  FeatureCheckInput,
+  FeatureSetAccessInput,
+  TrackUsageInput,
+  OnboardInput,
+  OnboardResult,
+  ApplyTierInput,
+  ClaimCheckoutInput,
+  LinkSubscriptionInput,
+} from "@chatarmin/os"
+```
+
+### Router Types
+
+```typescript
+import type { AppRouter } from "@chatarmin/os"
+```
+
+---
+
+## Configuration
+
+| Option    | Type     | Required | Default                           | Description                 |
+| --------- | -------- | -------- | --------------------------------- | --------------------------- |
+| `apiKey`  | `string` | ✅       | —                                 | API key from OS admin panel |
+| `baseUrl` | `string` | —        | `https://os.chatarmin.com/api/v1` | API endpoint                |
 
 ```typescript
-import type { AppRouter } from "@chatarmin/os-sdk"
+const os = new ChatarminOS({
+  apiKey: process.env.OS_API_KEY!,
+  baseUrl: "https://os.chatarmin.com/api/v1", // Default
+})
+
+// Local development
+const osLocal = new ChatarminOS({
+  apiKey: process.env.OS_API_KEY!,
+  baseUrl: "http://localhost:3001/api/v1",
+})
 ```
 
+### Getting Your API Key
+
+1. Go to ChatarminOS → **Settings** → **Developers** → **API Keys**
+2. Click "Create API Key"
+3. Copy the key (format: `os_sk_xxxxxxxxxxxx`)
+4. Store in environment variables
+
+---
+
+## Error Handling
+
+The SDK uses tRPC under the hood. Errors include structured information:
+
+```typescript
+try {
+  await os.billing.trackUsage({
+    companyId: "comp_xxx",
+    featureCode: "ai_credit",
+    quantity: 1000,
+  })
+} catch (error) {
+  if (error instanceof TRPCClientError) {
+    console.error("Code:", error.data?.code) // e.g., 'FORBIDDEN'
+    console.error("Message:", error.message) // Human-readable message
+    console.error("HTTP Status:", error.data?.httpStatus)
+  }
+}
+```
+
+### Common Error Codes
+
+| Code                  | Description                |
+| --------------------- | -------------------------- |
+| `UNAUTHORIZED`        | Invalid or missing API key |
+| `FORBIDDEN`           | No access to this resource |
+| `NOT_FOUND`           | Company/feature not found  |
+| `BAD_REQUEST`         | Invalid input parameters   |
+| `PRECONDITION_FAILED` | Usage limit exceeded       |
+
+---
+
+## Related Documentation
+
+- **[QUICKSTART.md](./QUICKSTART.md)** — Quick publishing & installation guide
+- **[PUBLISHING.md](./PUBLISHING.md)** — Detailed publishing instructions
+- **[test-sdk.ts](./test-sdk.ts)** — Complete usage examples
+
+---
+
+## Support
+
+- **Email**: hello@chatarmin.com
+- **Documentation**: https://os.chatarmin.com/docs
+
+---
+
 ## License
 
 MIT © Chatarmin GmbH

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@chatarmin/os",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Type-safe SDK for ChatarminOS - Customer & Subscription Management",
   "type": "module",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",