Add README and API docs

src/places.ts

@@ -31,11 +31,81 @@ const placeSchema = {
   required: ['id', 'title', 'lat', 'lon', 'geohash', 'createdAt'],
 } as const;
 
-type Place = FromSchema<typeof placeSchema> & { [key: string]: any };
+/**
+ * Represents a Place object.
+ *
+ * Core properties enforced by schema:
+ * - `id`: Unique identifier (ULID)
+ * - `title`: Name of the place
+ * - `lat`: Latitude
+ * - `lon`: Longitude
+ * - `geohash`: Geohash for indexing
+ * - `createdAt`: ISO date string
+ *
+ * Optional properties:
+ * - `description`: Text description
+ * - `zoom`: Map zoom level
+ * - `url`: Related URL
+ * - `osmId`, `osmType`, `osmTags`: OpenStreetMap data
+ * - `tags`: Array of string tags
+ * - `updatedAt`: ISO date string
+ */
+export type Place = FromSchema<typeof placeSchema> & { [key: string]: any };
+
+export interface PlacesClient {
+  /**
+   * Store a place.
+   * Generates ID and Geohash if missing.
+   * Path structure: <geohash-prefix-2>/<geohash-prefix-2>/<id>
+   *
+   * @param placeData - The data of the place to store.
+   * @returns The stored place object.
+   */
+  store(placeData: Partial<Place>): Promise<Place>;
+
+  /**
+   * Remove a place.
+   * Requires geohash to locate the folder.
+   *
+   * @param id - The ID of the place to remove.
+   * @param geohash - The geohash of the place.
+   */
+  remove(id: string, geohash: string): Promise<unknown>;
+
+  /**
+   * Get a single place.
+   * Requires geohash to locate the folder.
+   *
+   * @param id - The ID of the place to retrieve.
+   * @param geohash - The geohash of the place.
+   * @returns The place object.
+   */
+  get(id: string, geohash: string): Promise<Place | unknown>;
+
+  /**
+   * List places matching a geohash prefix.
+   * Supports 2-char ("ab") or 4-char ("abcd") prefixes.
+   * If 2-char, it returns the sub-folders (prefixes), not places.
+   * If 4-char, it returns the places in that sector.
+   *
+   * @param prefix - The geohash prefix to filter by.
+   * @returns A map of objects found at the prefix.
+   */
+  listByPrefix(prefix: string): Promise<unknown | { [key: string]: any }>;
+
+  /**
+   * Get places from specific prefixes.
+   *
+   * @param prefixes - Optional array of 4-character geohash prefixes to load (e.g. ['w1q7', 'w1q8']).
+   *                 If not provided, it will attempt to scan ALL prefixes (recursive).
+   * @returns An array of places.
+   */
+  getPlaces(prefixes?: string[]): Promise<Place[]>;
+}
 
 const Places = function (
   privateClient: BaseClient /*, publicClient: BaseClient */
-) {
+): { exports: PlacesClient } {
   // Define Schema
   privateClient.declareType('place', placeSchema as any);