@sales-planner/http-client 0.12.0 → 0.13.0

package/README.md

@@ -17,7 +17,7 @@ import { SalesPlannerClient } from '@sales-planner/http-client';
 
 const client = new SalesPlannerClient({
   baseUrl: 'https://sales-planner-back.vercel.app',
-  getAuthToken: () => 'your-api-key',
+  apiKey: 'your-api-key',
 });
 
 // Check if API is healthy
@@ -25,321 +25,314 @@ const health = await client.getHealth();
 console.log(health); // { status: 'ok', version: '1.0.0' }
 ```
 
+### Shop Context
+
+Most operations require a shop context (`ctx`) as the **first argument**:
+
+```typescript
+const ctx = { tenant_id: 1, shop_id: 1 };
+
+// All entity methods follow: client.<entity>.<method>(ctx, ...args)
+const skus = await client.skus.getSkus(ctx);
+const sku = await client.skus.getSku(ctx, 123);
+const brand = await client.brands.getBrandByCode(ctx, 'apple');
+```
+
 ### Namespaced Sub-Clients
 
 Access resources through domain-specific sub-clients:
 
 ```typescript
-// Users
+// Users (system-level, no ctx)
 const users = await client.users.getUsers();
 const user = await client.users.getUser(1);
 
-// Tenants & Shops
+// Tenants (system-level, no ctx)
 const tenants = await client.tenants.getTenants();
-const shops = await client.shops.getShops(tenantId);
 
-// SKUs with import/export
-const skus = await client.skus.getSkus({ tenantId, shopId });
-await client.skus.importJson(items, { tenantId, shopId });
-const csv = await client.skus.exportCsv({ tenantId, shopId });
-
-// Brands with import/export
-const brands = await client.brands.getBrands({ tenantId, shopId });
-await client.brands.importJson(items, { tenantId, shopId });
-const brandsCsv = await client.brands.exportCsv({ tenantId, shopId });
-
-// Categories with import/export
-const categories = await client.categories.getCategories({ tenantId, shopId });
-await client.categories.importJson(items, { tenantId, shopId });
+// Shops (tenant-level)
+const shops = await client.shops.getShops(tenantId);
 
-// Groups with import/export
-const groups = await client.groups.getGroups({ tenantId, shopId });
-await client.groups.importJson(items, { tenantId, shopId });
+// Shop-scoped entities (require ctx)
+const ctx = { tenant_id: 1, shop_id: 1 };
 
-// Statuses with import/export
-const statuses = await client.statuses.getStatuses({ tenantId, shopId });
-await client.statuses.importJson(items, { tenantId, shopId });
+// SKUs
+const skus = await client.skus.getSkus(ctx);
+await client.skus.createSku(ctx, { code: 'SKU-001', title: 'Product 1' });
+await client.skus.importJson(ctx, items);
+const csv = await client.skus.exportCsv(ctx);
 
-// Suppliers with import/export
-const suppliers = await client.suppliers.getSuppliers({ tenantId, shopId });
-await client.suppliers.importJson(items, { tenantId, shopId });
-const suppliersCsv = await client.suppliers.exportCsv({ tenantId, shopId });
+// Brands
+const brands = await client.brands.getBrands(ctx);
+await client.brands.importJson(ctx, [{ code: 'apple', title: 'Apple' }]);
 
-// Sales History
-const history = await client.salesHistory.getSalesHistory(
-  { tenantId, shopId },
-  { start: '2024-01', end: '2024-12' }
-);
+// Categories, Groups, Statuses, Suppliers - same pattern
+const categories = await client.categories.getCategories(ctx);
+const groups = await client.groups.getGroups(ctx);
+const statuses = await client.statuses.getStatuses(ctx);
+const suppliers = await client.suppliers.getSuppliers(ctx);
 
 // Marketplaces
-const marketplaces = await client.marketplaces.getMarketplaces({ tenantId });
+const marketplaces = await client.marketplaces.getMarketplaces(ctx);
 
-// Entity Metadata (for UI documentation)
+// Sales History (with optional period filter)
+const history = await client.salesHistory.getSalesHistory(ctx, {
+  start: '2024-01',
+  end: '2024-12',
+});
+
+// Entity Metadata (no auth required)
 const metadata = await client.metadata.getEntitiesMetadata();
-// Returns field definitions for brands, categories, groups, statuses, suppliers, marketplaces, skus, sales history
 ```
 
-## Import/Export Pattern
+## API Conventions
+
+### Argument Order
 
-Resources that support bulk operations (SKUs, Brands, Categories, Groups, Statuses, Suppliers, Sales History, Marketplaces) follow a consistent pattern:
+All methods follow a consistent pattern: **context first, then other arguments**.
 
 ```typescript
-// Import from JSON
-const result = await client.skus.importJson(
-  [
-    { code: 'SKU-001', title: 'Product 1' },
-    { code: 'SKU-002', title: 'Product 2' },
-  ],
-  { tenantId, shopId }
-);
-// Returns: { created: 2, updated: 0, errors: [] }
-
-// Import from CSV file
-const csvContent = await fs.readFile('skus.csv', 'utf-8');
-const result = await client.skus.importCsv(csvContent, { tenantId, shopId });
+// Get by ID
+await client.skus.getSku(ctx, id);
+await client.brands.getBrand(ctx, id);
 
-// Export to CSV
-const csv = await client.skus.exportCsv({ tenantId, shopId });
+// Get by code
+await client.skus.getSkuByCode(ctx, code);
+await client.brands.getBrandByCode(ctx, code);
 
-// Get example templates (no auth required)
-const exampleCsv = await client.skus.getExampleCsv();
+// Create
+await client.skus.createSku(ctx, request);
+await client.brands.createBrand(ctx, request);
 
-// Same pattern works for brands, categories, groups, statuses
-const brandResult = await client.brands.importJson(
-  [{ code: 'apple', title: 'Apple' }],
-  { tenantId, shopId }
-);
-
-const categoryResult = await client.categories.importJson(
-  [{ code: 'electronics', title: 'Electronics' }],
-  { tenantId, shopId }
-);
-
-const groupResult = await client.groups.importJson(
-  [{ code: 'smartphones', title: 'Smartphones' }],
-  { tenantId, shopId }
-);
-
-const statusResult = await client.statuses.importJson(
-  [{ code: 'active', title: 'Active' }],
-  { tenantId, shopId }
-);
-```
+// Update
+await client.skus.updateSku(ctx, id, request);
+await client.brands.updateBrand(ctx, id, request);
 
-## Data Requirements
+// Delete
+await client.skus.deleteSku(ctx, id);
+await client.brands.deleteBrand(ctx, id);
 
-### SKUs
+// Import
+await client.skus.importJson(ctx, items);
+await client.skus.importCsv(ctx, csvContent);
 
-**Create/Import:**
-- `code` (required): String, 1-100 characters, unique per shop
-- `title` (required): String, 1-200 characters
+// Export
+await client.skus.exportJson(ctx);
+await client.skus.exportCsv(ctx);
+```
 
-**Update:**
-- `code` (optional): String, 1-100 characters
-- `title` (optional): String, 1-200 characters
+### IDs vs Codes
 
-### Brands
+- **Create/Update operations** use numeric IDs for references (e.g., `marketplace_id`)
+- **Import/Export operations** use string codes for human readability (e.g., `marketplace: 'amazon'`)
 
-**Create/Import:**
-- `code` (required): String, 1-100 characters, unique per shop
-- `title` (required): String, 1-200 characters
+```typescript
+// Create uses IDs
+await client.salesHistory.createSalesHistory(ctx, {
+  sku_id: 123,
+  marketplace_id: 1,
+  period: '2026-01',
+  quantity: 100,
+});
 
-**Update:**
-- `code` (optional): String, 1-100 characters
-- `title` (optional): String, 1-200 characters
+// Import uses codes (auto-resolves to IDs)
+await client.salesHistory.importJson(ctx, [
+  { sku: 'SKU-001', marketplace: 'amazon', period: '2026-01', quantity: 100 },
+]);
 
-### Categories
+// Export returns codes
+const exported = await client.salesHistory.exportJson(ctx);
+// [{ sku: 'SKU-001', marketplace: 'amazon', period: '2026-01', quantity: 100 }]
+```
 
-**Create/Import:**
-- `code` (required): String, 1-100 characters, unique per shop
-- `title` (required): String, 1-200 characters
+## Import/Export Pattern
 
-**Update:**
-- `code` (optional): String, 1-100 characters
-- `title` (optional): String, 1-200 characters
+All shop-scoped entities support bulk import/export:
 
-### Groups
+```typescript
+const ctx = { tenant_id: 1, shop_id: 1 };
 
-**Create/Import:**
-- `code` (required): String, 1-100 characters, unique per shop
-- `title` (required): String, 1-200 characters
+// Import from JSON array
+const result = await client.skus.importJson(ctx, [
+  { code: 'SKU-001', title: 'Product 1' },
+  { code: 'SKU-002', title: 'Product 2' },
+]);
+console.log(result); // { created: 2, updated: 0, errors: [] }
 
-**Update:**
-- `code` (optional): String, 1-100 characters
-- `title` (optional): String, 1-200 characters
+// Import from CSV string
+const csvContent = `code,title
+SKU-001,Product 1
+SKU-002,Product 2`;
+const result = await client.skus.importCsv(ctx, csvContent);
 
-### Statuses
+// Export to JSON
+const items = await client.skus.exportJson(ctx);
 
-**Create/Import:**
-- `code` (required): String, 1-100 characters, unique per shop
-- `title` (required): String, 1-200 characters
+// Export to CSV
+const csv = await client.skus.exportCsv(ctx);
 
-**Update:**
-- `code` (optional): String, 1-100 characters
-- `title` (optional): String, 1-200 characters
+// Get example templates (no auth required)
+const exampleJson = await client.skus.getExampleJson();
+const exampleCsv = await client.skus.getExampleCsv();
+```
 
-### Suppliers
+**Supported entities:** SKUs, Brands, Categories, Groups, Statuses, Suppliers, Marketplaces, Sales History
 
-**Create/Import:**
-- `code` (required): String, 1-100 characters, unique per shop
-- `title` (required): String, 1-200 characters
+## Data Requirements
 
-**Update:**
-- `code` (optional): String, 1-100 characters
-- `title` (optional): String, 1-200 characters
+### SKUs
 
-### Sales History
+| Field | Create/Import | Update | Export |
+|-------|---------------|--------|--------|
+| `code` | Required, unique per shop | Optional | ✓ |
+| `title` | Required | Optional | ✓ |
+| `title2` | Optional | Optional | ✓ |
+| `category` | Optional (code) | - | code |
+| `group` | Optional (code) | - | code |
+| `status` | Optional (code) | - | code |
+| `supplier` | Optional (code) | - | code |
 
-**Create:**
-- `sku_id` (required): Number, must reference existing SKU
-- `period` (required): String, format `YYYY-MM` (e.g., "2026-01")
-- `quantity` (required): Number, integer
-- `marketplace_id` (required): Number, must reference existing marketplace
+### Brands, Categories, Groups, Statuses, Suppliers
 
-**Import (CSV/JSON):**
-- `sku_code` (required): String, must match existing SKU or will be auto-created
-- `period` (required): String, format `YYYY-MM` (e.g., "2026-01")
-- `quantity` (required): Number, integer
-- `marketplace` (required): String (marketplace code), must match existing marketplace or will be auto-created
+| Field | Create/Import | Update | Export |
+|-------|---------------|--------|--------|
+| `code` | Required, unique per shop | Optional | ✓ |
+| `title` | Required | Optional | ✓ |
 
-Note: Import endpoints accept marketplace codes for convenience, but the API internally uses numeric marketplace IDs. Export also returns marketplace codes.
+### Marketplaces
 
-**Update:**
-- `sku_id` (optional): Number
-- `period` (optional): String, format `YYYY-MM`
-- `quantity` (optional): Number
-- `marketplace_id` (optional): Number
+| Field | Create/Import | Update | Export |
+|-------|---------------|--------|--------|
+| `code` | Required, unique per shop | Optional | ✓ |
+| `title` | Required | Optional | ✓ |
 
-### Users
+### Sales History
+
+| Field | Create | Import | Update | Export |
+|-------|--------|--------|--------|--------|
+| `sku_id` | Required | - | Optional | - |
+| `sku` | - | Required (code) | - | code |
+| `marketplace_id` | Required | - | Optional | - |
+| `marketplace` | - | Required (code) | - | code |
+| `period` | Required (YYYY-MM) | Required | Optional | ✓ |
+| `quantity` | Required | Required | Optional | ✓ |
 
-**Create:**
-- `email` (required): String, valid email format, unique
-- `name` (required): String, 1-200 characters
-- `default_shop_id` (optional): Number
+### Users
 
-**Update:**
-- `email` (optional): String, valid email format
-- `name` (optional): String, 1-200 characters
-- `default_shop_id` (optional): Number or null
+| Field | Create | Update |
+|-------|--------|--------|
+| `email` | Required, unique | Optional |
+| `name` | Required | Optional |
+| `default_shop_id` | Optional | Optional (null to clear) |
 
 ### Tenants
 
-**Create:**
-- `title` (required): String, 1-200 characters
-- `owner_id` (optional): Number, user ID
-
-**Update:**
-- `title` (optional): String, 1-200 characters
-- `owner_id` (optional): Number or null
+| Field | Create | Update |
+|-------|--------|--------|
+| `title` | Required | Optional |
+| `owner_id` | Optional | Optional (null to clear) |
 
 ### Shops
 
-**Create:**
-- `title` (required): String, 1-200 characters
-- `tenant_id` (required): Number
-
-**Update:**
-- `title` (optional): String, 1-200 characters
-
-### Marketplaces
-
-**Create:**
-- `code` (required): String, 1-100 characters, unique (e.g., "amazon", "ebay")
-- `title` (required): String, 1-200 characters
-
-**Update:**
-- `code` (optional): String, 1-100 characters
-- `title` (optional): String, 1-200 characters
+| Field | Create | Update |
+|-------|--------|--------|
+| `title` | Required | Optional |
+| `tenant_id` | Required | - |
 
 ## Available Sub-Clients
 
-Each sub-client is accessed via `client.<subClient>.<method>()`.
+### System-Level (no context required)
 
-### `client.me`
+#### `client.me`
 - `getMe()` - Get current user with roles and tenants
 
-### `client.users`
-- `getUsers()`, `getUser(id)` - System admin or tenant admin (filtered by their tenants)
-- `createUser(dto)`, `deleteUser(id)` - Tenant admin or higher
-
-### `client.tenants`
-- `getTenants()`, `getTenant(id)` - All authenticated users
-- `createTenant(dto)` - System admin only
-- `updateTenant(id, dto)`, `deleteTenant(id)` - Authenticated users (validation happens server-side)
-- `createTenantWithShopAndUser(dto)` - System admin only
-
-### `client.shops`
-- `getShops(tenantId?)`, `getShop(id)`, `createShop(dto)`, `updateShop(id, dto)`, `deleteShop(id)` - Requires tenant access
+#### `client.users`
+- `getUsers()` - List users (system admin sees all, tenant admin sees their tenants)
+- `getUser(id)` - Get user by ID
+- `createUser(request)` - Create user
+- `updateUser(id, request)` - Update user
+- `deleteUser(id)` - Delete user
+
+#### `client.tenants`
+- `getTenants()` - List tenants
+- `getTenant(id)` - Get tenant by ID
+- `createTenant(request)` - Create tenant (system admin only)
+- `updateTenant(id, request)` - Update tenant
+- `deleteTenant(id)` - Delete tenant
+- `createTenantWithShopAndUser(request)` - Create tenant with initial shop and user
+
+#### `client.shops`
+- `getShops(tenantId?)` - List shops (optionally filtered by tenant)
+- `getShop(id)` - Get shop by ID
+- `createShop(request)` - Create shop
+- `updateShop(id, request)` - Update shop
+- `deleteShop(id)` - Delete shop
 - `deleteShopData(id)` - Delete all data (SKUs, sales history) for a shop
 
-### `client.skus`
-- `getSkus(ctx)`, `getSku(id, ctx)`, `getSkuByCode(code, ctx)` - Requires read access (viewer or higher)
-- `createSku(dto, ctx)`, `updateSku(id, dto, ctx)`, `deleteSku(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access
-- `exportJson(ctx)`, `exportCsv(ctx)` - Requires read access
-- `getExampleJson()`, `getExampleCsv()` - Get import format examples (no auth required)
-
-### `client.brands`
-- `getBrands(ctx)`, `getBrand(id, ctx)`, `getBrandByCode(code, ctx)` - Requires read access (viewer or higher)
-- `createBrand(dto, ctx)`, `updateBrand(id, dto, ctx)`, `deleteBrand(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access (bulk upsert by code)
-- `exportJson(ctx)`, `exportCsv(ctx)` - Requires read access
-- `getExampleJson()`, `getExampleCsv()` - Get import format examples (no auth required)
-
-### `client.categories`
-- `getCategories(ctx)`, `getCategory(id, ctx)`, `getCategoryByCode(code, ctx)` - Requires read access (viewer or higher)
-- `createCategory(dto, ctx)`, `updateCategory(id, dto, ctx)`, `deleteCategory(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access (bulk upsert by code)
-- `exportJson(ctx)`, `exportCsv(ctx)` - Requires read access
-- `getExampleJson()`, `getExampleCsv()` - Get import format examples (no auth required)
-
-### `client.groups`
-- `getGroups(ctx)`, `getGroup(id, ctx)`, `getGroupByCode(code, ctx)` - Requires read access (viewer or higher)
-- `createGroup(dto, ctx)`, `updateGroup(id, dto, ctx)`, `deleteGroup(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access (bulk upsert by code)
-- `exportJson(ctx)`, `exportCsv(ctx)` - Requires read access
-- `getExampleJson()`, `getExampleCsv()` - Get import format examples (no auth required)
-
-### `client.statuses`
-- `getStatuses(ctx)`, `getStatus(id, ctx)`, `getStatusByCode(code, ctx)` - Requires read access (viewer or higher)
-- `createStatus(dto, ctx)`, `updateStatus(id, dto, ctx)`, `deleteStatus(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access (bulk upsert by code)
-- `exportJson(ctx)`, `exportCsv(ctx)` - Requires read access
-- `getExampleJson()`, `getExampleCsv()` - Get import format examples (no auth required)
-
-### `client.suppliers`
-- `getSuppliers(ctx)`, `getSupplier(id, ctx)`, `getSupplierByCode(code, ctx)` - Requires read access (viewer or higher)
-- `createSupplier(dto, ctx)`, `updateSupplier(id, dto, ctx)`, `deleteSupplier(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access (bulk upsert by code)
-- `exportJson(ctx)`, `exportCsv(ctx)` - Requires read access
-- `getExampleJson()`, `getExampleCsv()` - Get import format examples (no auth required)
-
-### `client.salesHistory`
-- `getSalesHistory(ctx, query?)`, `getSalesHistoryItem(id, ctx)` - Requires read access (viewer or higher)
-- `createSalesHistory(dto, ctx)`, `updateSalesHistory(id, dto, ctx)`, `deleteSalesHistory(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access
-- `exportJson(ctx, query?)`, `exportCsv(ctx, query?)` - Requires read access
-- `getExampleJson()`, `getExampleCsv()` - Get import format examples (no auth required)
-
-### `client.roles`
-- `getRoles()`, `getRole(id)` - System admin only
-- `createRole(dto)`, `updateRole(id, dto)`, `deleteRole(id)` - System admin only
-
-### `client.userRoles`
-- `getUserRoles(query)`, `getUserRole(id)` - View roles for tenant
-- `createUserRole(dto)`, `deleteUserRole(id)` - Tenant admin or higher for their tenant
-
-### `client.apiKeys`
-- `getApiKeys()`, `createApiKey(dto)`, `deleteApiKey(id)` - System admin only
-
-### `client.marketplaces`
-- `getMarketplaces(ctx)`, `getMarketplace(id, ctx)`, `getMarketplaceByCode(code, ctx)` - Requires read access
-- `createMarketplace(dto, ctx)`, `updateMarketplace(id, dto, ctx)`, `deleteMarketplace(id, ctx)` - Requires write access (editor or higher)
-- `importJson(items, ctx)`, `importCsv(csvContent, ctx)` - Requires write access
-- `exportJson(ctx)`, `exportCsv(ctx)` - Requires read access
-
-### `client.metadata`
-- `getEntitiesMetadata()` - Get field definitions for all entities (no auth required)
+#### `client.roles`
+- `getRoles()` - List roles (system admin only)
+- `getRole(id)` - Get role by ID
+
+#### `client.userRoles`
+- `getUserRoles(query)` - List user roles
+- `getUserRole(id)` - Get user role by ID
+- `createUserRole(request)` - Create user role
+- `deleteUserRole(id)` - Delete user role
+
+#### `client.apiKeys`
+- `getApiKeys()` - List API keys (system admin only)
+- `createApiKey(request)` - Create API key
+- `deleteApiKey(id)` - Delete API key
+
+#### `client.metadata`
+- `getEntitiesMetadata()` - Get field definitions for all entities (no auth)
+
+### Shop-Scoped (context required)
+
+All shop-scoped clients follow the same pattern:
+
+#### `client.skus`
+- `getSkus(ctx)` - List SKUs
+- `getSku(ctx, id)` - Get SKU by ID
+- `getSkuByCode(ctx, code)` - Get SKU by code
+- `createSku(ctx, request)` - Create SKU
+- `updateSku(ctx, id, request)` - Update SKU
+- `deleteSku(ctx, id)` - Delete SKU
+- `importJson(ctx, items)` - Import from JSON array
+- `importCsv(ctx, csvContent)` - Import from CSV string
+- `exportJson(ctx)` - Export to JSON
+- `exportCsv(ctx)` - Export to CSV
+- `getExampleJson()` - Get JSON import example (no auth)
+- `getExampleCsv()` - Get CSV import example (no auth)
+
+#### `client.brands`, `client.categories`, `client.groups`, `client.statuses`, `client.suppliers`
+
+Same methods as `client.skus`:
+- `get<Entity>s(ctx)`, `get<Entity>(ctx, id)`, `get<Entity>ByCode(ctx, code)`
+- `create<Entity>(ctx, request)`, `update<Entity>(ctx, id, request)`, `delete<Entity>(ctx, id)`
+- `importJson(ctx, items)`, `importCsv(ctx, csvContent)`
+- `exportJson(ctx)`, `exportCsv(ctx)`
+- `getExampleJson()`, `getExampleCsv()`
+
+#### `client.marketplaces`
+- `getMarketplaces(ctx)` - List marketplaces
+- `getMarketplace(ctx, id)` - Get marketplace by ID
+- `getMarketplaceByCode(ctx, code)` - Get marketplace by code
+- `createMarketplace(ctx, request)` - Create marketplace
+- `updateMarketplace(ctx, id, request)` - Update marketplace
+- `deleteMarketplace(ctx, id)` - Delete marketplace
+- `importJson(ctx, items)`, `importCsv(ctx, csvContent)` - Import
+- `exportJson(ctx)`, `exportCsv(ctx)` - Export
+
+#### `client.salesHistory`
+- `getSalesHistory(ctx, query?)` - List sales history (optional period filter)
+- `getSalesHistoryItem(ctx, id)` - Get sales history item by ID
+- `createSalesHistory(ctx, request)` - Create sales history
+- `updateSalesHistory(ctx, id, request)` - Update sales history
+- `deleteSalesHistory(ctx, id)` - Delete sales history
+- `importJson(ctx, items)`, `importCsv(ctx, csvContent)` - Import
+- `exportJson(ctx, query?)`, `exportCsv(ctx, query?)` - Export (optional period filter)
+- `getExampleJson()`, `getExampleCsv()` - Examples (no auth)
 
 ## Error Handling
 
@@ -356,35 +349,71 @@ try {
 }
 ```
 
-Common HTTP status codes:
-- `409 Conflict` - Duplicate resource (email, SKU code, sales period)
-- `404 Not Found` - Resource not found
-- `403 Forbidden` - Insufficient permissions
+**Common HTTP status codes:**
 - `400 Bad Request` - Validation error
+- `401 Unauthorized` - Missing or invalid API key
+- `403 Forbidden` - Insufficient permissions
+- `404 Not Found` - Resource not found
+- `409 Conflict` - Duplicate resource (email, code, period)
 
 ## Types
 
-Common types are re-exported from `@sales-planner/shared` for convenience:
+Types are re-exported from `@sales-planner/shared`:
 
 ```typescript
-import type { 
+import type {
+  // Context
+  ShopContextParams,
+  PeriodQuery,
+
   // Entities
-  User, Tenant, Shop, Sku, SalesHistory, Role, UserRole, ApiKey, Marketplace,
-  // DTOs
-  CreateUserDto, CreateTenantDto, CreateShopDto,
-  CreateSkuDto, CreateSkuRequest, CreateSalesHistoryDto, CreateSalesHistoryRequest,
-  CreateMarketplaceDto, CreateMarketplaceRequest,
-  // Query types
-  ShopContextParams, PeriodQuery,
+  User,
+  Tenant,
+  Shop,
+  Sku,
+  Brand,
+  Category,
+  Group,
+  Status,
+  Supplier,
+  Marketplace,
+  SalesHistory,
+  Role,
+  UserRole,
+  ApiKey,
+
+  // Request types (for create/update)
+  CreateUserRequest,
+  UpdateUserRequest,
+  CreateTenantRequest,
+  UpdateTenantRequest,
+  CreateShopRequest,
+  UpdateShopRequest,
+  CreateSkuRequest,
+  UpdateSkuRequest,
+  CreateBrandRequest,
+  UpdateBrandRequest,
+  CreateSalesHistoryRequest,
+  UpdateSalesHistoryRequest,
+  // ... etc
+
+  // Import types (for import operations)
+  ImportSkuItem,
+  ImportBrandItem,
+  ImportSalesHistoryItem,
+  // ... etc
+
   // Response types
-  UserWithRolesAndTenants, TenantWithShopAndApiKey,
-  ImportResult, DeleteDataResult,
-  SkuExportItem, SalesHistoryExportItem,
+  UserWithRolesAndTenants,
+  TenantWithShopAndApiKey,
+  ImportResult,
+  SkuImportResult,
+  DeleteDataResult,
+
+  // Export types
+  SkuExportItem,
+  SalesHistoryExportItem,
 } from '@sales-planner/http-client';
-
-// For additional types (Brand, Category, Group, Status, Supplier, etc.)
-// import directly from @sales-planner/shared
-import type { Brand, Category, Group, Status, Supplier } from '@sales-planner/shared';
 ```
 
 ## License