@fjell/client-api 4.4.43 → 4.4.45

package/MIGRATION_v3.md

@@ -0,0 +1,231 @@
+# Migration Guide: v4.4.x to v4.5.0
+
+## Overview
+
+Version 4.5.0 adopts the Operations interface from `@fjell/core`, providing a consistent API across all Fjell packages.
+
+## Breaking Changes Summary
+
+1. **Core Operations Interface**: `ClientApi` now extends `Operations` from `@fjell/core`
+2. **Create Method**: Changed signature to use `CreateOptions`
+3. **Action Methods**: Parameter name changed from `body` to `params`
+4. **Upsert Operation**: Added missing `upsert` method
+
+## Dependency Updates
+
+Update your `package.json`:
+
+```bash
+npm install @fjell/core@latest @fjell/client-api@latest
+```
+
+## Code Migration
+
+### 1. Create Method
+
+The `create` method now uses `CreateOptions` instead of a simple `locations` parameter.
+
+#### Before (v4.4.x)
+
+```typescript
+// With locations
+const item = await api.create(
+  { name: 'Alice' },
+  [{ kt: 'org', lk: 'org-123' }]
+);
+
+// Without locations
+const item = await api.create({ name: 'Alice' });
+```
+
+#### After (v4.5.0)
+
+```typescript
+// With locations - wrap in options object
+const item = await api.create(
+  { name: 'Alice' },
+  { locations: [{ kt: 'org', lk: 'org-123' }] }
+);
+
+// Without locations - omit options or pass undefined
+const item = await api.create({ name: 'Alice' });
+
+// NEW: With specific key
+const item = await api.create(
+  { name: 'Alice' },
+  { key: { kt: 'user', pk: 'custom-id' } }
+);
+```
+
+### 2. Action Methods
+
+The parameter name changed from `body` to `params` to match the core Operations interface. **Functionally, it's the same** - just a naming change.
+
+#### Before (v4.4.x)
+
+```typescript
+const [item, affectedKeys] = await api.action(
+  key,
+  'promote',
+  { role: 'admin' } // called "body"
+);
+
+const [items, affectedKeys] = await api.allAction(
+  'archive',
+  { reason: 'expired' }, // called "body"
+  locations
+);
+```
+
+#### After (v4.5.0)
+
+```typescript
+// Same code - just know it's now called "params" internally
+const [item, affectedKeys] = await api.action(
+  key,
+  'promote',
+  { role: 'admin' } // now called "params"
+);
+
+const [items, affectedKeys] = await api.allAction(
+  'archive',
+  { reason: 'expired' }, // now called "params"
+  locations
+);
+```
+
+### 3. Upsert Operation (New)
+
+A new `upsert` operation is now available:
+
+```typescript
+// Creates if doesn't exist, updates if it does
+const user = await api.upsert(
+  { kt: 'user', pk: 'user-123' },
+  { name: 'Alice', email: 'alice@example.com' }
+);
+
+// With locations (for contained items)
+const comment = await api.upsert(
+  { kt: 'comment', pk: 'comment-456', loc: [{ kt: 'post', lk: 'post-123' }] },
+  { text: 'Updated comment' },
+  [{ kt: 'post', lk: 'post-123' }]
+);
+```
+
+### 4. Type Imports
+
+Import types from the appropriate package:
+
+#### Before (v4.4.x)
+
+```typescript
+import { ClientApi } from '@fjell/client-api';
+// No OperationParams or AffectedKeys available
+```
+
+#### After (v4.5.0)
+
+```typescript
+import { ClientApi, OperationParams, AffectedKeys, CreateOptions } from '@fjell/client-api';
+// Or import directly from core
+import { Operations, OperationParams, AffectedKeys } from '@fjell/core';
+```
+
+## Type Compatibility
+
+The `ClientApi` interface is now fully compatible with the core `Operations` interface:
+
+```typescript
+import type { Operations } from '@fjell/core';
+import type { ClientApi } from '@fjell/client-api';
+
+// These are now compatible
+function processItems(ops: Operations<User, 'user'>) {
+  // Can pass either ClientApi or any other Operations implementation
+}
+
+const clientApi: ClientApi<User, 'user'> = ...;
+processItems(clientApi); // ✅ Works!
+```
+
+## Benefits of Migration
+
+### 1. Consistent Interface
+
+All Fjell packages now share the same Operations interface:
+
+```typescript
+// All implement the same Operations interface
+import { Operations } from '@fjell/lib';
+import { ClientApi } from '@fjell/client-api';
+import { Operations as FirestoreOps } from '@fjell/lib-firestore';
+
+// Can be used interchangeably
+function workWithOperations(ops: Operations<Item, string>) {
+  // Works with any implementation
+}
+```
+
+### 2. Better Type Safety
+
+```typescript
+import { OperationParams, AffectedKeys, CreateOptions } from '@fjell/core';
+
+// Strongly typed parameters
+const params: OperationParams = {
+  status: 'active',
+  limit: 10
+};
+
+// Type-safe create options
+const options: CreateOptions<'user'> = {
+  key: { kt: 'user', pk: 'user-123' }
+};
+```
+
+### 3. Future Compatibility
+
+By adopting the core interface, your code will be compatible with future Fjell enhancements and new operation implementations.
+
+## Troubleshooting
+
+### TypeScript Errors
+
+If you see TypeScript errors after upgrading:
+
+1. **Clear your TypeScript cache**: Delete `node_modules/.cache` and `dist/` directories
+2. **Rebuild**: Run `npm run build`
+3. **Update imports**: Ensure you're importing types from the correct packages
+
+### Runtime Errors
+
+If you encounter runtime errors:
+
+1. **Check create calls**: Wrap `locations` in options object: `{ locations: [...] }`
+2. **Verify dependencies**: Ensure `@fjell/core` is at the latest version
+3. **Clear node_modules**: Delete and reinstall if necessary
+
+## Migration Checklist
+
+- [ ] Update package.json dependencies
+- [ ] Run `npm install`
+- [ ] Update `create` calls to use options object
+- [ ] Update any type imports
+- [ ] Test upsert operations if needed
+- [ ] Run tests: `npm test`
+- [ ] Build: `npm run build`
+- [ ] Check for TypeScript errors: `npm run lint`
+
+## Questions or Issues?
+
+If you encounter any problems during migration:
+
+1. Check the [API Reference](./docs/public/api-reference.md)
+2. Review the [examples](./examples/)
+3. File an issue on GitHub
+
+## Previous Migrations
+
+- For migrations from older versions, see previous migration guides
+

package/README.md

@@ -0,0 +1,169 @@
+# @fjell/client-api
+
+HTTP client for Fjell operations.
+
+## Installation
+
+```bash
+npm install @fjell/client-api @fjell/http-api @fjell/core
+```
+
+## Overview
+
+`@fjell/client-api` provides HTTP client implementations for Fjell's Operations interface. It enables you to interact with Fjell-based APIs over HTTP using the same consistent interface as local operations.
+
+## v4.5.0+ Breaking Changes
+
+The `ClientApi` interface now directly extends `@fjell/core` Operations. This means:
+- Consistent interface across all transport layers
+- Better type safety
+- Smaller bundle size
+- Full compatibility with other Operations implementations
+
+### Key Changes
+
+1. **Core Operations Interface**: `ClientApi` now extends the core `Operations` interface
+2. **Upsert Support**: Added missing `upsert` operation
+3. **CreateOptions**: The `create` method now accepts `CreateOptions` for more flexibility
+4. **Action Parameters**: Action methods now use `params` (OperationParams) instead of `body`
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { createClientApi } from '@fjell/client-api';
+import { HttpApi } from '@fjell/http-api';
+import type { Item } from '@fjell/core';
+
+// Define your item type
+interface User extends Item<'user'> {
+  name: string;
+  email: string;
+}
+
+// Create HTTP API instance
+const httpApi = new HttpApi({ baseUrl: 'https://api.example.com' });
+
+// Create client API
+const userApi = createClientApi<User, 'user'>(
+  httpApi,
+  'user',
+  ['user']
+);
+
+// Use the operations
+const users = await userApi.all({});
+const user = await userApi.get({ kt: 'user', pk: 'user-123' });
+const created = await userApi.create({ name: 'Alice', email: 'alice@example.com' });
+const updated = await userApi.update({ kt: 'user', pk: 'user-123' }, { name: 'Alice Smith' });
+```
+
+### Contained Items
+
+```typescript
+import { createCItemApi } from '@fjell/client-api';
+
+interface Comment extends Item<'comment', 'post'> {
+  text: string;
+  author: string;
+}
+
+const commentApi = createCItemApi<Comment, 'comment', 'post'>(
+  httpApi,
+  'comment',
+  ['post', 'comment']
+);
+
+// Operations scoped to a specific location
+const comments = await commentApi.all({}, [{ kt: 'post', lk: 'post-123' }]);
+const comment = await commentApi.create(
+  { text: 'Great post!', author: 'alice' },
+  { locations: [{ kt: 'post', lk: 'post-123' }] }
+);
+```
+
+### All Operations
+
+The ClientApi implements all standard Operations:
+
+- **CRUD**: `get`, `create`, `update`, `upsert`, `remove`
+- **Query**: `all`, `one`, `find`, `findOne`
+- **Actions**: `action`, `allAction`
+- **Facets**: `facet`, `allFacet`
+
+## Migration from v4.4.x
+
+### Update Dependencies
+
+```bash
+npm install @fjell/core@latest @fjell/client-api@latest
+```
+
+### Code Changes
+
+The API is mostly backward compatible. Key changes:
+
+#### 1. Create Method Signature
+
+```typescript
+// Before (v4.4.x)
+await api.create(item, locations);
+
+// After (v4.5.0+) - still works
+await api.create(item, { locations });
+
+// New options
+await api.create(item, { key: { kt: 'user', pk: 'custom-id' } });
+```
+
+#### 2. Action Parameters
+
+```typescript
+// Before (v4.4.x) - "body" parameter
+await api.action(key, 'promote', { role: 'admin' });
+
+// After (v4.5.0+) - "params" parameter (works the same)
+await api.action(key, 'promote', { role: 'admin' });
+```
+
+#### 3. Upsert Operation
+
+```typescript
+// Now available
+const user = await api.upsert(
+  { kt: 'user', pk: 'user-123' },
+  { name: 'Alice', email: 'alice@example.com' }
+);
+```
+
+## Type Exports
+
+```typescript
+import type { 
+  ClientApi,
+  CItemApi,
+  OperationParams,
+  AffectedKeys,
+  CreateOptions
+} from '@fjell/client-api';
+```
+
+## Benefits
+
+- **Consistent API**: Same Operations interface as `@fjell/lib`, `@fjell/lib-firestore`, etc.
+- **Type Safety**: Full TypeScript support with generic types
+- **Interchangeable**: Can be used anywhere that accepts Operations
+- **HTTP Transport**: Built on `@fjell/http-api` for reliable HTTP communication
+
+## Documentation
+
+For detailed documentation, see:
+- [API Reference](./docs/public/api-reference.md)
+- [Examples](./examples/README.md)
+- [Migration Guide](./MIGRATION_v3.md)
+
+## License
+
+Apache-2.0
+

package/dist/AItemAPI.d.ts

@@ -1,4 +1,4 @@
-import { Item, QueryParams } from "@fjell/core";
+import { Item } from "@fjell/core";
 import { HttpApi } from "@fjell/http-api";
 import { ClientApiOptions } from "./ClientApiOptions";
 import { ClientApi } from "./ClientApi";
@@ -30,5 +30,5 @@ export type PathNamesArray<L1 extends string = never, L2 extends string = never,
     string,
     string
 ]);
-export declare const finderToParams: (finder: string, finderParams: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => QueryParams;
+export declare const finderToParams: (finder: string, finderParams: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Record<string, string>;
 export declare const createAItemAPI: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(api: HttpApi, pkType: S, pathNames: PathNamesArray<L1, L2, L3, L4, L5>, options?: ClientApiOptions) => ClientApi<V, S, L1, L2, L3, L4, L5>;

package/dist/CItemAPI.d.ts

@@ -1,19 +1,12 @@
-import { ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { Item } from "@fjell/core";
 import { HttpApi } from "@fjell/http-api";
 import { PathNamesArray } from "./AItemAPI";
 import { ClientApi } from "./ClientApi";
 import { ClientApiOptions } from "./ClientApiOptions";
+/**
+ * CItemApi extends ClientApi for contained items.
+ * No additional methods needed - pure Operations interface.
+ */
 export interface CItemApi<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends ClientApi<V, S, L1, L2, L3, L4, L5> {
-    action: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body: any) => Promise<[V, Array<PriKey<any> | ComKey<any, any, any, any, any, any> | LocKeyArray<any, any, any, any, any>>]>;
-    all: (query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V[]>;
-    allAction: (action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[V[], Array<PriKey<any> | ComKey<any, any, any, any, any, any> | LocKeyArray<any, any, any, any, any>>]>;
-    allFacet: (facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<any>;
-    get: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<V | null>;
-    create: (item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V>;
-    remove: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<boolean>;
-    update: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Partial<Item<S, L1, L2, L3, L4, L5>>) => Promise<V>;
-    facet: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<any>;
-    find: (finder: string, finderParams?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V[]>;
-    findOne: (finder: string, finderParams?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V>;
 }
 export declare const createCItemApi: <V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(api: HttpApi, type: S, pathNames: PathNamesArray<L1, L2, L3, L4, L5>, options?: ClientApiOptions) => CItemApi<V, S, L1, L2, L3, L4, L5>;

package/dist/ClientApi.d.ts

@@ -1,15 +1,14 @@
-import { ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
-export interface ClientApi<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> {
-    action: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, action: string, body?: any) => Promise<[V, Array<PriKey<any> | ComKey<any, any, any, any, any, any> | LocKeyArray<any, any, any, any, any>>]>;
-    all: (query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V[]>;
-    allAction: (action: string, body?: any, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<[V[], Array<PriKey<any> | ComKey<any, any, any, any, any, any> | LocKeyArray<any, any, any, any, any>>]>;
-    allFacet: (facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<any>;
-    create: (item: Partial<Item<S, L1, L2, L3, L4, L5>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V>;
-    facet: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<any>;
-    find: (finder: string, finderParams?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V[]>;
-    findOne: (finder: string, finderParams?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V>;
-    get: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<V | null>;
-    one: (query: ItemQuery, locations?: LocKeyArray<L1, L2, L3, L4, L5> | []) => Promise<V | null>;
-    remove: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>) => Promise<boolean>;
-    update: (ik: ComKey<S, L1, L2, L3, L4, L5> | PriKey<S>, item: Partial<Item<S, L1, L2, L3, L4, L5>>) => Promise<V>;
+import { AffectedKeys, Operations as CoreOperations, CreateOptions, Item, OperationParams } from "@fjell/core";
+export type { OperationParams, AffectedKeys, CreateOptions };
+/**
+ * ClientApi interface - HTTP transport layer for Operations.
+ * This is a direct mapping of the core Operations interface to HTTP calls.
+ *
+ * @example
+ * ```typescript
+ * const api: ClientApi<User, 'user'> = createClientApi(httpApi, 'user', ['user']);
+ * const users = await api.all({});
+ * ```
+ */
+export interface ClientApi<V extends Item<S, L1, L2, L3, L4, L5>, S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> extends CoreOperations<V, S, L1, L2, L3, L4, L5> {
 }

package/dist/Instance.d.ts

@@ -1,6 +1,7 @@
 import { Item } from "@fjell/core";
-import { Instance as BaseInstance, Coordinate, Registry } from "@fjell/registry";
+import { Instance as BaseInstance, Registry } from "@fjell/registry";
 import { ClientApi } from "./ClientApi";
+import { Coordinate } from "@fjell/core";
 /**
  * The Client API Instance interface represents a client API model instance that extends the base Instance
  * from @fjell/registry and adds client API operations for interacting with remote data.

package/dist/PItemAPI.d.ts

@@ -1,19 +1,7 @@
-import { ComKey, Item, ItemQuery, LocKeyArray, PriKey } from "@fjell/core";
+import { Item } from "@fjell/core";
 import { HttpApi } from "@fjell/http-api";
 import { ClientApi } from "./ClientApi";
 import { ClientApiOptions } from "./ClientApiOptions";
 export interface PItemApi<V extends Item<S>, S extends string> extends ClientApi<V, S> {
-    action: (ik: PriKey<S> | ComKey<S, never, never, never, never, never>, action: string, body: any) => Promise<[V, Array<PriKey<any> | ComKey<any, any, any, any, any, any> | LocKeyArray<any, any, any, any, any>>]>;
-    all: (query: ItemQuery) => Promise<V[]>;
-    allAction: (action: string, body?: any) => Promise<[V[], Array<PriKey<any> | ComKey<any, any, any, any, any, any> | LocKeyArray<any, any, any, any, any>>]>;
-    allFacet: (facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<any>;
-    one: (query: ItemQuery) => Promise<V | null>;
-    get: (ik: PriKey<S> | ComKey<S, never, never, never, never, never>) => Promise<V | null>;
-    create: (item: Partial<Item<S>>) => Promise<V>;
-    remove: (ik: PriKey<S> | ComKey<S, never, never, never, never, never>) => Promise<boolean>;
-    update: (ik: PriKey<S> | ComKey<S, never, never, never, never, never>, item: Partial<Item<S>>) => Promise<V>;
-    facet: (ik: PriKey<S> | ComKey<S, never, never, never, never, never>, facet: string, params?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<any>;
-    find: (finder: string, finderParams?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<V[]>;
-    findOne: (finder: string, finderParams?: Record<string, string | number | boolean | Date | Array<string | number | boolean | Date>>) => Promise<V>;
 }
 export declare const createPItemApi: <V extends Item<S>, S extends string>(api: HttpApi, type: S, pathName: string, options?: ClientApiOptions) => PItemApi<V, S>;

package/dist/index.d.ts

@@ -9,4 +9,5 @@ export * from './InstanceFactory';
 export * from './Registry';
 export * from './errors/index';
 export * from './ops/errorHandling';
+export { FjellHttpError, isFjellHttpError, extractErrorInfo, type ErrorInfo } from '@fjell/http-api';
 export * from './http/HttpWrapper';