@gettersethya/mira-client 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Getter Sethya
+
+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,140 @@
+# @gettersethya/mira-client
+
+> **Early pre-alpha.** Breaking changes may occur without notice.
+
+Type-safe client SDK for [Mira](https://github.com/gettersethya/mira). Works in the browser and Node.js (SSR). Every operation returns a handler with both a Promise interface (`.raw()`) and an Effect interface (`.toEffect()`).
+
+## Installation
+
+```bash
+npm install @gettersethya/mira-client @gettersethya/mira-collection effect
+# or
+pnpm add @gettersethya/mira-client @gettersethya/mira-collection effect
+```
+
+## Setup
+
+```typescript
+import { createMiraClient } from "@gettersethya/mira-client"
+import { Posts, Users } from "./collections.js"
+
+// Browser — token stored automatically in a cookie
+const mira = createMiraClient("/").withCollections({ posts: Posts, users: Users })
+
+// Server — token managed manually
+const mira = createMiraClient("http://localhost:3000", { type: "server" })
+  .withCollections({ posts: Posts, users: Users })
+```
+
+## Queries
+
+```typescript
+// Paginated list — returns { items, nextCursor }
+const { items, nextCursor } = await mira.posts.getList({
+  filter: (f) => f.field("published").eq(true),
+  sort:   "created",
+  order:  "desc",
+  limit:  10,
+  cursor: null,
+  expand: ["authorId"],
+  select: ["id", "title", "authorId"],
+}).raw()
+
+// Single record by id
+const post = await mira.posts.getOne("post-id").raw()
+
+// First match or nothing (returns Option<T>)
+const latest = await mira.posts.getFirstOrNone({
+  filter: (f) => f.field("published").eq(true),
+  sort:   "created",
+  order:  "desc",
+}).raw()
+
+// All records as a flat array (no pagination)
+const all = await mira.posts.getFullList({ limit: 5000 }).raw()
+```
+
+## Mutations
+
+```typescript
+// Create
+const post = await mira.posts.create().raw({ title: "Hello", published: false })
+
+// Create with file upload — pass File or Blob for file fields
+const post = await mira.posts.create().raw({
+  title:     "With Image",
+  thumbnail: new File([bytes], "thumb.png", { type: "image/png" }),
+})
+
+// Update
+const updated = await mira.posts.update().raw(["post-id", { title: "Updated" }])
+
+// Delete
+await mira.posts.delete().raw("post-id")
+```
+
+## Authentication
+
+```typescript
+// Login — token stored automatically (browser) or set manually (server)
+const { token, record } = await mira.users.authWithPassword().raw({
+  email:    "user@example.com",
+  password: "password123",
+})
+
+// Server: set the token after login
+mira.auth.setToken(token)
+
+// Check login state
+mira.auth.loggedIn()  // boolean
+
+// Logout
+mira.auth.logout()
+```
+
+## Effect-based usage
+
+Every handler exposes `.toEffect()` for use inside Effect pipelines.
+
+```typescript
+import { Effect } from "effect"
+
+const effect = mira.posts.getList({ limit: 10 }).toEffect()
+// Effect.Effect<{ items: Post[], nextCursor: number | null }, MiraError, HttpClient>
+
+Effect.gen(function* () {
+  const { items } = yield* mira.posts.getList({ limit: 10 }).toEffect()
+  const post      = yield* mira.posts.getOne("post-id").toEffect()
+})
+```
+
+## File URLs
+
+```typescript
+import { buildFileUrl } from "@gettersethya/mira-client"
+
+// Public file
+const url = buildFileUrl("posts", postId, "thumb.png")
+
+// Protected file — request a short-lived token first
+const res = await fetch("/api/files/token", {
+  method:  "POST",
+  headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+  body:    JSON.stringify({ collection: "posts" }),
+})
+const { token: fileToken } = await res.json()
+const url = `${buildFileUrl("posts", postId, "thumb.png")}?token=${fileToken}`
+```
+
+## Type inference
+
+```typescript
+import type { InferRecord, InferCreateInput } from "@gettersethya/mira-client"
+
+type Post        = InferRecord<typeof Posts>        // full record with system fields
+type NewPost     = InferCreateInput<typeof Posts>   // creation input, no system fields
+```
+
+## More
+
+See the [Mira root README](https://github.com/gettersethya/mira) for full documentation.

package/dist/src/client/auth.d.ts

@@ -0,0 +1,73 @@
+import type { HttpClient } from "@effect/platform";
+import { Effect, MutableRef } from "effect";
+import type { MiraError } from "./errors.js";
+import type { ClientHandler, ExecuteFn } from "./handler.js";
+/**
+ * Browser-side authentication helper.
+ *
+ * The server sets an HttpOnly cookie (`mira_token`) on successful login. The
+ * browser sends it automatically on every same-origin request — the client
+ * never reads or writes it directly.
+ *
+ * Because the cookie is HttpOnly, the client cannot tell on page load whether
+ * a session exists. Call `refresh()` once on app startup to re-validate the
+ * cookie against the server and restore `isLoggedIn()` state.
+ *
+ * `clear()` calls `POST /api/auth/logout` to clear the cookie server-side,
+ * then resets the in-memory login flag.
+ *
+ * @see ServerAuth — server-side alternative for SSR environments
+ */
+export type BrowserAuth = {
+    /** True if the user logged in during this page session or `refresh()` confirmed a valid cookie. */
+    isLoggedIn(): boolean;
+    /**
+     * Calls `GET /api/auth/me` to check whether a valid `mira_token` cookie exists.
+     * Sets the in-memory login flag to match the server's answer.
+     * Call this once on app startup to restore login state after a page reload.
+     *
+     * @returns true if a valid session exists, false otherwise
+     */
+    refresh(): Promise<boolean>;
+    /** Calls `POST /api/auth/logout` to clear the server cookie, then resets the login flag. */
+    clear(): void;
+};
+/**
+ * Server-side authentication helper. Stores the JWT token in a `MutableRef`
+ * for manual management (e.g., during SSR hydration).
+ *
+ * The `token` getter/setter provides direct access to the raw JWT string.
+ * `isValid()` checks the JWT `exp` claim against the current time without
+ * making an HTTP request — it only validates expiry, not signature.
+ *
+ * @example
+ * import { createMiraClient } from "@gettersethya/mira-client"
+ *
+ * const mira = createMiraClient("/", { type: "server" })
+ * mira.auth.setToken("eyJ...")  // set token from SSR context
+ * console.log(mira.auth.isValid())  // true if token is not expired
+ * const currentToken = mira.auth.token  // "eyJ..."
+ * mira.auth.clear()  // clears token and file token cache
+ *
+ * @see BrowserAuth — browser-side alternative
+ */
+export type ServerAuth = {
+    token: string | null;
+    setToken(token: string): void;
+    clear(): void;
+    isValid(): boolean;
+};
+/**
+ * Factory function for `BrowserAuth`. Called internally by `createMiraClient` in browser mode.
+ * @internal Use `createMiraClient()` instead of calling this directly
+ */
+export declare function makeBrowserAuth(execute: ExecuteFn, makeClientHandler: <T>(effect: Effect.Effect<T, MiraError, HttpClient.HttpClient>) => ClientHandler<T>, loggedInRef: MutableRef.MutableRef<boolean>): BrowserAuth;
+/**
+ * Factory function for `ServerAuth`. Called internally by `createMiraClient` in server mode.
+ * @internal Use `createMiraClient("/", { type: "server" })` instead of calling this directly
+ */
+export declare function makeServerAuth(authTokenRef: MutableRef.MutableRef<string | null>, fileTokenCacheRef: MutableRef.MutableRef<Map<string, {
+    token: string;
+    expiresAt: number;
+}>>): ServerAuth;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/client/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/client/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,mGAAmG;IACnG,UAAU,IAAI,OAAO,CAAA;IACrB;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IAC3B,4FAA4F;IAC5F,KAAK,IAAI,IAAI,CAAA;CACd,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,KAAK,IAAI,IAAI,CAAA;IACb,OAAO,IAAI,OAAO,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,EAClB,iBAAiB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,EACtG,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,GAC1C,WAAW,CA0Bb;AAcD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,EAClD,iBAAiB,EAAE,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,GAC1F,UAAU,CAoBZ"}

package/dist/src/client/auth.js

@@ -0,0 +1,72 @@
+import { HttpClientRequest as HCR } from "@effect/platform";
+import { Effect, MutableRef } from "effect";
+/**
+ * Factory function for `BrowserAuth`. Called internally by `createMiraClient` in browser mode.
+ * @internal Use `createMiraClient()` instead of calling this directly
+ */
+export function makeBrowserAuth(execute, makeClientHandler, loggedInRef) {
+    return {
+        isLoggedIn: () => MutableRef.get(loggedInRef),
+        refresh: async () => {
+            try {
+                const effect = execute(HCR.get("/api/auth/me"));
+                await makeClientHandler(effect).raw();
+                MutableRef.set(loggedInRef, true);
+                return true;
+            }
+            catch {
+                MutableRef.set(loggedInRef, false);
+                return false;
+            }
+        },
+        clear: () => {
+            const effect = Effect.gen(function* () {
+                yield* execute(HCR.post("/api/auth/logout"));
+                MutableRef.set(loggedInRef, false);
+            });
+            void makeClientHandler(effect).raw();
+        },
+    };
+}
+function decodeJwtExp(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return null;
+        const payload = JSON.parse(globalThis.atob(parts[1].replace(/-/g, "+").replace(/_/g, "/")));
+        if (typeof payload.exp === "number")
+            return payload.exp;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Factory function for `ServerAuth`. Called internally by `createMiraClient` in server mode.
+ * @internal Use `createMiraClient("/", { type: "server" })` instead of calling this directly
+ */
+export function makeServerAuth(authTokenRef, fileTokenCacheRef) {
+    return {
+        get token() {
+            return MutableRef.get(authTokenRef);
+        },
+        setToken(token) {
+            MutableRef.set(authTokenRef, token);
+        },
+        clear: () => {
+            MutableRef.set(authTokenRef, null);
+            MutableRef.set(fileTokenCacheRef, new Map());
+        },
+        isValid: () => {
+            const token = MutableRef.get(authTokenRef);
+            if (token === null)
+                return false;
+            const exp = decodeJwtExp(token);
+            if (exp === null)
+                return false;
+            return Date.now() < exp * 1000;
+        },
+    };
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/client/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/client/auth.ts"],"names":[],"mappings":"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"}

package/dist/src/client/collection.d.ts

@@ -0,0 +1,239 @@
+import { MutableRef, Option, Schedule } from "effect";
+import type { AnyCollectionDef, FieldsMap, InferFieldValue, FilterNode, FieldFilterOperand } from "@gettersethya/mira-collection";
+import { MiraError } from "./errors.js";
+import type { ClientHandler, ExecuteFn } from "./handler.js";
+import type { CollectionFileFields, InferMutationInput, InferRecord, RelationKeys, WithExpand } from "./types.js";
+/**
+ * Optional retry configuration for collection operations.
+ * Wraps an Effect `Schedule` that determines retry behavior when a `MiraError` occurs.
+ *
+ * If not provided, the operation is not retried. Set at the collection level via
+ * `defaultRetryOptions` in `createMiraClient()` or per-call via the `retryOptions` parameter.
+ *
+ * @example
+ * import { Schedule } from "effect"
+ *
+ * const retry: RetryOptions = {
+ *   schedule: Schedule.exponential(100)  // retry with exponential backoff starting at 100ms
+ * }
+ *
+ * @see createMiraClient — accepts defaultRetryOptions
+ * @see CollectionClient — each method accepts retryOptions
+ */
+export type RetryOptions = {
+    schedule?: Schedule.Schedule<unknown, MiraError, never>;
+};
+type GetListOptions<F extends FieldsMap, E extends ReadonlyArray<string>> = {
+    filter?: (f: FilterBuilder<F>) => FilterNode;
+    sort?: keyof F & string;
+    order?: "asc" | "desc";
+    cursor?: number | null;
+    limit?: number;
+    select?: ReadonlyArray<keyof F & string>;
+    expand?: E;
+    retryOptions?: RetryOptions;
+};
+type GetOneOptions<F extends FieldsMap, E extends ReadonlyArray<string>> = {
+    select?: ReadonlyArray<keyof F & string>;
+    expand?: E;
+    retryOptions?: RetryOptions;
+};
+/**
+ * Typed filter builder used inside `CollectionClient` callback methods.
+ * Same shape as `FilterBuilder<F>` in `filter/builder.ts` but re-exported
+ * from the client module for convenience.
+ *
+ * @example
+ * const posts = await mira.posts.getList({
+ *   filter: (f) => f.and(
+ *     f.field("published").eq(true),
+ *     f.field("views").gte(100)
+ *   )
+ * }).raw()
+ *
+ * @see CollectionClient.getList — accepts filter callback
+ * @see Filter — untyped filter builder
+ */
+export type FilterBuilder<F extends FieldsMap> = {
+    field<K extends keyof F & string>(name: K): FieldFilterOperand<InferFieldValue<F[K]>>;
+    and(left: FilterNode, right: FilterNode): FilterNode;
+    or(left: FilterNode, right: FilterNode): FilterNode;
+    not(node: FilterNode): FilterNode;
+};
+/**
+ * Client interface for a single collection, providing typed CRUD operations.
+ * Created via `makeCollectionClient()` or automatically via `createMiraClient()`.
+ *
+ * All query methods return `ClientHandler` — call `.raw()` for Promise-based usage
+ * or `.toEffect()` for Effect-based usage.
+ * All mutation methods return a mutation `ClientHandler` — call `.raw(input)` with
+ * the data payload.
+ *
+ * @typeParam F - The FieldsMap type of the collection
+ *
+ * @example
+ * const posts = mira.posts  // inferred as CollectionClient<PostFields>
+ * const list = await posts.getList({ sort: "created", order: "desc" }).raw()
+ * const one = await posts.getOne("abc123").raw()
+ * const created = await posts.create().raw({ title: "hello", body: "world" })
+ *
+ * @see makeCollectionClient — constructs CollectionClient instances
+ * @see ClientHandler — return type of all methods
+ */
+export type CollectionClient<F extends FieldsMap> = {
+    /**
+     * List records with optional filtering, sorting, cursor pagination, and field selection.
+     *
+     * Returns `{ items, nextCursor }` where `nextCursor` is `null` when there are
+     * no more pages. Pagination is cursor-based — iterate by passing the previous
+     * response's `nextCursor` as the `cursor` option.
+     *
+     * @example
+     * let cursor: number | null = null
+     * do {
+     *   const { items, nextCursor } = await posts.getList({ cursor, limit: 20 }).raw()
+     *   cursor = nextCursor
+     * } while (cursor !== null)
+     *
+     * @param options.filter - Optional filter callback using the typed FilterBuilder
+     * @param options.sort - Field name to sort by
+     * @param options.order - Sort direction: "asc" or "desc" (default: "asc")
+     * @param options.cursor - Cursor for pagination (from previous response's nextCursor)
+     * @param options.limit - Maximum items per page (server default applies if omitted)
+     * @param options.select - Subset of field names to include in the response
+     * @param options.expand - Relation field names to expand (fetches related records)
+     * @param options.retryOptions - Optional retry schedule
+     * @returns ClientHandler for the paginated result
+     */
+    getList<E extends ReadonlyArray<RelationKeys<F>> = []>(options?: GetListOptions<F, E>): ClientHandler<{
+        items: WithExpand<F, E>[];
+        nextCursor: number | null;
+    }>;
+    /**
+     * Get the first record matching a filter, or `Option.none()` if none match.
+     *
+     * **Requires a `filter` callback** — unlike `getList`, the filter is mandatory.
+     * Internally calls `getList` with `limit: 1` and extracts the first item.
+     *
+     * @param filter - Filter callback (required) — use `(f) => f.field("id").eq("x")` etc.
+     * @param options.sort - Field name to sort by (determines which is "first")
+     * @param options.order - Sort direction
+     * @param options.select - Subset of field names to include
+     * @param options.expand - Relation field names to expand
+     * @param options.retryOptions - Optional retry schedule
+     * @returns ClientHandler resolving to Option of the record (None if no match)
+     */
+    getFirstOrNone<E extends ReadonlyArray<RelationKeys<F>> = []>(filter: (f: FilterBuilder<F>) => FilterNode, options?: Omit<GetListOptions<F, E>, "filter" | "limit" | "cursor">): ClientHandler<Option.Option<WithExpand<F, E>>>;
+    /**
+     * Fetch all records matching the filter, automatically following pagination.
+     * Defaults to `limit: 1000` — override via options if you need a different page size.
+     *
+     * Unlike `getList` which returns a single page with `nextCursor`,
+     * `getFullList` fetches pages internally and returns a flat array.
+     *
+     * @param options.filter - Optional filter callback
+     * @param options.sort - Field name to sort by
+     * @param options.order - Sort direction
+     * @param options.limit - Page size for internal pagination (default: 1000)
+     * @param options.select - Subset of field names to include
+     * @param options.expand - Relation field names to expand
+     * @param options.retryOptions - Optional retry schedule
+     * @returns ClientHandler resolving to a flat array of records
+     */
+    getFullList<E extends ReadonlyArray<RelationKeys<F>> = []>(options?: Omit<GetListOptions<F, E>, "limit" | "cursor"> & {
+        limit?: number;
+    }): ClientHandler<WithExpand<F, E>[]>;
+    /**
+     * Get a single record by its `id`.
+     * Returns a 404 `MiraError` if the record does not exist.
+     *
+     * @param id - The record ID (string UUID)
+     * @param options.select - Subset of field names to include
+     * @param options.expand - Relation field names to expand
+     * @param options.retryOptions - Optional retry schedule
+     * @returns ClientHandler resolving to the record
+     */
+    getOne<E extends ReadonlyArray<RelationKeys<F>> = []>(id: string, options?: GetOneOptions<F, E>): ClientHandler<WithExpand<F, E>>;
+    /**
+     * Create a new record.
+     *
+     * When the input contains any `File` or `Blob` values (for file fields), the
+     * request is automatically dispatched as `multipart/form-data` instead of JSON.
+     *
+     * @returns A mutation ClientHandler — call `.raw(input)` with the record data
+     */
+    create(): ClientHandler<InferRecord<F>, InferMutationInput<F>>;
+    /**
+     * Update an existing record by ID.
+     * Only the fields present in `data` are updated (partial/patch semantics).
+     *
+     * When `data` contains any `File` or `Blob` values, the request is automatically
+     * dispatched as `multipart/form-data`.
+     *
+     * @returns A mutation ClientHandler — call `.raw({ id, data })`
+     */
+    update(): ClientHandler<InferRecord<F>, {
+        id: string;
+        data: Partial<InferMutationInput<F>>;
+    }>;
+    /**
+     * Delete a record by ID.
+     * Returns `void` on success. Throws `MiraError` (404) if the record does not exist.
+     *
+     * @returns A mutation ClientHandler — call `.raw(id)` with the record ID
+     */
+    delete(): ClientHandler<void, string>;
+    /**
+     * Authenticate with email and password on an auth collection.
+     * Only available on collections defined with `AuthCollection.define()`.
+     * On success, stores the returned JWT token for subsequent requests.
+     *
+     * @example
+     * const { token, record } = await mira.users.authWithPassword().raw({
+     *   email: "user@example.com",
+     *   password: "secret123"
+     * })
+     *
+     * @returns A mutation ClientHandler — call `.raw({ email, password })`
+     */
+    authWithPassword?(): ClientHandler<{
+        token: string;
+        record: InferRecord<F>;
+    }, {
+        email: string;
+        password: string;
+    }>;
+    /**
+     * File field client interfaces for the collection.
+     * Provides `.url()` and `.asyncUrl()` methods for constructing file download URLs.
+     *
+     * @example
+     * const url = posts.fields.cover.url(post.id, "cover.jpg")
+     */
+    fields: CollectionFileFields<F>;
+};
+type MakeCollectionClientParams<F extends FieldsMap> = {
+    collectionName: string;
+    schema: AnyCollectionDef["schema"];
+    fields: F;
+    execute: ExecuteFn;
+    baseUrl: string;
+    authTokenRef: MutableRef.MutableRef<string | null> | null;
+    loggedInRef: MutableRef.MutableRef<boolean> | null;
+    fileTokenCacheRef: MutableRef.MutableRef<Map<string, {
+        token: string;
+        expiresAt: number;
+    }>>;
+    isAuth: boolean;
+    defaultRetryOptions?: RetryOptions;
+};
+/**
+ * Construct a `CollectionClient<F>` for a given collection definition.
+ * This is the internal factory — users should use `createMiraClient()` which
+ * handles all wiring (auth, execute, file fields).
+ *
+ * @internal Use `createMiraClient().collection(def)` or `withCollections()` instead.
+ */
+export declare function makeCollectionClient<F extends FieldsMap>(params: MakeCollectionClientParams<F>): CollectionClient<F>;
+export {};
+//# sourceMappingURL=collection.d.ts.map

package/dist/src/client/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../../src/client/collection.ts"],"names":[],"mappings":"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"}