geogridapi 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,560 @@
+declare const DEFAULT_BASE_URL = "https://api.geogridapi.io";
+interface ClientOptions {
+    /** API key (`gga_live_…` or `gga_test_…`). Defaults to `process.env.GEOGRIDAPI_API_KEY`. */
+    apiKey?: string;
+    /** Defaults to `https://api.geogridapi.io`. */
+    baseURL?: string;
+    /** Timeout of each HTTP request, in milliseconds (default 60 000). */
+    timeoutMs?: number;
+    /** Retries on network errors, 429 and 5xx (default 2). Grid and batch creations are retried with the same idempotency key. */
+    maxRetries?: number;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxRetries?: number;
+}
+interface IdempotentRequestOptions extends RequestOptions {
+    /** Same key = same grid or batch, never charged twice. Generated when omitted. */
+    idempotencyKey?: string;
+}
+type QueryValue = string | number | boolean | undefined;
+interface RequestSpec {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    path: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    idempotencyKey?: string;
+    /** Safe to send again after a network error or a 5xx. */
+    retryable: boolean;
+    binary?: boolean;
+}
+declare class Transport {
+    #private;
+    private readonly baseURL;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options?: ClientOptions);
+    /** Whether the key is a test key (free mock grids). */
+    get isTestKey(): boolean;
+    private buildURL;
+    private headers;
+    request<T>(spec: RequestSpec, options?: RequestOptions): Promise<T>;
+    /** One HTTP exchange. A caller abort is rethrown as is; everything else becomes a GeoGridAPIError. */
+    private attempt;
+}
+
+type GridShape = "square" | "circle" | "diamond" | "hexagon" | "cross" | "ellipse" | "rectangle";
+type GridDensity = "low" | "medium" | "high";
+type GridSize = 3 | 5 | 7 | 9;
+type GridStatus = "pending" | "running" | "completed" | "failed";
+type KeyMode = "live" | "test";
+interface Center {
+    lat: number;
+    lng: number;
+}
+/** Format shared by a grid, an estimate and a batch. */
+interface GridFormat {
+    /** Grid shape (default `square`). */
+    shape?: GridShape;
+    /** Square only (default 7): side of the grid, size × size points. */
+    size?: GridSize;
+    /** Other shapes only (default `medium`). */
+    density?: GridDensity;
+    /** Distance from center to edge, 0.5 to 30 km (other shapes: from 1 km). */
+    radius_km?: number;
+    /** Search language, 2-letter code. Defaults to the account language. */
+    language?: string;
+    /** Search country, 2-letter ISO code. */
+    country?: string;
+    /** Public HTTPS URL called with the grid when it ends (`grid.completed` or `grid.failed`). */
+    webhook_url?: string;
+}
+interface TargetBase {
+    /** Keyword searched on Google Maps. */
+    keyword: string;
+    /** Grid center; defaults to the listing's location. */
+    center?: Center;
+}
+/** The listing to measure: a Google place id, or a name and city (first match). */
+type GridTarget = TargetBase & ({
+    place_id: string;
+    query?: never;
+} | {
+    query: string;
+    place_id?: never;
+});
+type CreateGridParams = GridTarget & GridFormat;
+interface Place {
+    place_id: string;
+    name: string | null;
+    address: string | null;
+    lat: number;
+    lng: number;
+}
+/** A listing named without its coordinates (history, batch items). */
+type PlaceRef = Pick<Place, "place_id" | "name" | "address">;
+/** Why a grid or a batch item failed. */
+interface GridError {
+    code: string;
+    message: string;
+}
+/** A search result; `lat`/`lng` are `null` when Google gives no public location (service-area business). */
+interface FoundPlace extends PlaceRef {
+    lat: number | null;
+    lng: number | null;
+}
+interface PlaceList {
+    object: "list";
+    data: FoundPlace[];
+}
+interface GridSummary {
+    /** Mean rank over the points where the listing appears. */
+    average_rank: number | null;
+    /** Mean rank with misses counted as 21. */
+    average_rank_with_misses: number | null;
+    top3_points: number;
+    found_points: number;
+}
+interface TopListing {
+    rank: number;
+    place_id: string;
+    name: string;
+}
+interface GridPoint {
+    /** 0 = north. */
+    row: number;
+    /** 0 = west. */
+    col: number;
+    lat: number;
+    lng: number;
+    /** Position in the Google Maps results at this point; `null` = not in the top 20. */
+    rank: number | null;
+    /** Top 3 listings at this point. */
+    top: TopListing[];
+}
+interface Competitor {
+    place_id: string;
+    name: string;
+    /** Points where it is in the top 3. */
+    top3_points: number;
+    /** Points where it ranks first. */
+    first_points: number;
+    /** Points where it ranks ahead of your listing. */
+    ahead_points: number;
+}
+/** Change since the previous grid of the same map (same listing, keyword, format, radius and center). */
+interface PreviousGrid {
+    grid_id: string;
+    created_at: string;
+    average_rank: number | null;
+    top3_points: number;
+    found_points: number;
+    changes: {
+        /** Negative = better. */
+        average_rank: number | null;
+        top3_points: number;
+        found_points: number;
+    };
+    ranks: (number | null)[][];
+    /** Places gained per cell (positive = better, a miss counts as 21). */
+    rank_changes: (number | null)[][];
+    points: {
+        improved: number;
+        worsened: number;
+        unchanged: number;
+    };
+}
+interface Grid {
+    id: string;
+    object: "grid";
+    status: GridStatus;
+    mode: KeyMode;
+    source: "api" | "mcp" | "console";
+    api_key_id: string | null;
+    place: Place;
+    keyword: string;
+    shape: GridShape;
+    density: GridDensity | null;
+    size: number;
+    rows: number;
+    cols: number;
+    radius_km: number;
+    language: string;
+    country: string | null;
+    /** Grid points measured (points at sea are neither measured nor charged). */
+    points_total: number;
+    /** Credits charged (0 with a test key). */
+    points_charged: number;
+    summary: GridSummary | null;
+    /** rows × cols matrix, row 0 = north, column 0 = west. `null` = not in the top 20 (or outside the shape). */
+    ranks: (number | null)[][] | null;
+    points?: GridPoint[] | null;
+    /** Who ranks ahead: the top 3 listings summed over the map. */
+    competitors?: Competitor[] | null;
+    previous?: PreviousGrid | null;
+    /** Why the grid failed (`null` unless `status` is `failed`). */
+    error: GridError | null;
+    /** Delivery of the `webhook_url`, when one was given. */
+    webhook?: {
+        status: string | null;
+        attempts: number;
+    } | null;
+    created_at: string;
+    completed_at: string | null;
+}
+interface ListGridsParams {
+    /** 1 to 100 (default 20). */
+    limit?: number;
+    /** `next_before` of the previous page. */
+    before?: string;
+    place_id?: string;
+    /** Exact keyword, case-insensitive. */
+    keyword?: string;
+}
+interface GridList {
+    object: "list";
+    data: Grid[];
+    has_more: boolean;
+    /** Pass as `before` to read the next page. */
+    next_before: string | null;
+}
+interface Estimate {
+    object: "estimate";
+    shape: GridShape;
+    size: number;
+    density: GridDensity | null;
+    rows: number;
+    cols: number;
+    radius_km: number;
+    /** Points that will be measured (points at sea removed). */
+    points: number;
+    points_at_sea: number;
+    /** `false`: the listing could not be located, `points` is an upper bound. */
+    exact: boolean;
+    /** Credits the grid will cost. */
+    credits: number;
+    balance?: number;
+    balance_after?: number;
+    enough?: boolean;
+    place: Place | null;
+}
+type HistoryParams = {
+    limit?: number;
+} & ({
+    grid_id: string;
+    place_id?: never;
+    keyword?: never;
+} | {
+    place_id: string;
+    keyword: string;
+    grid_id?: never;
+});
+interface HistoryEntry {
+    grid_id: string;
+    created_at: string;
+    average_rank: number | null;
+    top3_points: number;
+    found_points: number;
+    points_total: number;
+}
+interface History {
+    object: "history";
+    reference_grid_id: string;
+    mode: KeyMode;
+    place: PlaceRef;
+    keyword: string;
+    shape: GridShape;
+    density: GridDensity | null;
+    size: number;
+    rows: number;
+    cols: number;
+    radius_km: number;
+    /** Completed grids of the same map, oldest first. */
+    data: HistoryEntry[];
+    has_more: boolean;
+    change: {
+        since: string;
+        /** Negative = better. */
+        average_rank: number | null;
+        top3_points: number;
+        found_points: number;
+    } | null;
+}
+type CreateBatchParams = GridFormat & {
+    /** 1 to 50 grids: one listing with several keywords, or several listings with one keyword. */
+    items: GridTarget[];
+};
+type BatchItemStatus = "queued" | "pending" | "running" | "completed" | "failed";
+interface BatchItem {
+    index: number;
+    keyword: string;
+    query: string | null;
+    place: PlaceRef | null;
+    status: BatchItemStatus;
+    grid_id: string | null;
+    points_total: number | null;
+    points_charged: number;
+    summary: Pick<GridSummary, "average_rank" | "top3_points" | "found_points"> | null;
+    error: GridError | null;
+}
+interface Batch {
+    id: string;
+    object: "batch";
+    status: "running" | "completed";
+    mode: KeyMode;
+    source: "api" | "mcp" | "console";
+    shape: GridShape;
+    size: number;
+    density: GridDensity | null;
+    radius_km: number;
+    items_count: number;
+    counts: Record<BatchItemStatus, number>;
+    credits_estimated: number;
+    credits_charged: number;
+    items: BatchItem[];
+    created_at: string;
+    launched_at: string | null;
+}
+interface CreateScheduleParams {
+    /** An existing completed grid to repeat. */
+    grid_id: string;
+    frequency: "weekly" | "monthly";
+    /** Weekly: 1 = Monday … 7 = Sunday (default 1). */
+    weekday?: number;
+    /** Monthly: day of the month, 1 to 28 (default 1). */
+    month_day?: number;
+}
+interface Schedule {
+    id: string;
+    object: "schedule";
+    status: "active" | "paused" | "stopped";
+    stopped_reason: string | null;
+    mode: KeyMode;
+    frequency: "weekly" | "monthly";
+    weekday: number | null;
+    month_day: number | null;
+    /** The listing and the grid center. */
+    place: Pick<Place, "place_id" | "name" | "lat" | "lng">;
+    keyword: string;
+    shape: GridShape;
+    density: GridDensity | null;
+    size: number;
+    radius_km: number;
+    points_per_run: number;
+    credits_per_month: number;
+    next_run_at: string | null;
+    last_run_at: string | null;
+    last_grid_id: string | null;
+    source_grid_id: string | null;
+    runs_count: number;
+    created_at: string;
+}
+interface ScheduleList {
+    object: "list";
+    data: Schedule[];
+}
+interface Balance {
+    object: "balance";
+    /** Credits left (1 credit = 1 grid point). */
+    points: number;
+    mode: KeyMode;
+}
+type WebhookEventType = "grid.completed" | "grid.failed";
+interface WebhookEvent {
+    id: string;
+    object: "event";
+    type: WebhookEventType;
+    created_at: string;
+    data: Grid;
+}
+
+interface WaitOptions {
+    /** First delay between two status reads, in milliseconds (grids: 3 000, batches: 5 000). It then grows up to 10 s. */
+    pollIntervalMs?: number;
+    /** Give up after this many milliseconds (grids: 300 000, batches: 900 000). The work keeps running server side. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+type RunOptions = IdempotentRequestOptions & {
+    wait?: WaitOptions;
+};
+declare class Places {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Finds a Google Business Profile by name and city, with its `place_id`. Free (a live key needs a positive balance). */
+    search(params: string | {
+        q: string;
+        language?: string;
+    }, options?: RequestOptions): Promise<PlaceList>;
+}
+declare class Grids {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Starts a grid (status `pending`); it completes in 20 seconds to 2 minutes.
+     * Costs 1 credit per point, refunded if the grid fails. Use `run` to wait for the result.
+     * Retries inside this call reuse one idempotency key; pass your own `idempotencyKey` to make your own retries safe too.
+     */
+    create(params: CreateGridParams, options?: IdempotentRequestOptions): Promise<Grid>;
+    /** Exact number of points and credits a grid would cost. Free, nothing is reserved. */
+    estimate(params: CreateGridParams, options?: RequestOptions): Promise<Estimate>;
+    /** Status and result of a grid: ranks, summary, competitors ahead and change since the previous grid. */
+    get(id: string, options?: RequestOptions): Promise<Grid>;
+    /** One page of grids, newest first, without point details. */
+    list(params?: ListGridsParams, options?: RequestOptions): Promise<GridList>;
+    /** Every grid, newest first, reading the pages as you iterate. */
+    listAll(params?: Omit<ListGridsParams, "before">, options?: RequestOptions): AsyncGenerator<Grid>;
+    /** PNG heatmap (1200 × 1092) of a completed grid. Free. */
+    image(id: string, params?: {
+        lang?: "en" | "fr";
+    }, options?: RequestOptions): Promise<Uint8Array>;
+    /** Reads the grid until it is `completed` or `failed`. */
+    wait(id: string, options?: WaitOptions): Promise<Grid>;
+    /** Starts a grid and waits for its result (`completed` or `failed`; a failed grid is refunded). */
+    run(params: CreateGridParams, options?: RunOptions): Promise<Grid>;
+}
+declare class Batches {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Up to 50 grids with the same format: one listing with several keywords, or several listings with one keyword.
+     * Each grid is charged when it starts and refunded if it fails.
+     */
+    create(params: CreateBatchParams, options?: IdempotentRequestOptions): Promise<Batch>;
+    /** A batch and the status of each of its grids. */
+    get(id: string, options?: RequestOptions): Promise<Batch>;
+    /** Reads the batch until every grid is finished. */
+    wait(id: string, options?: WaitOptions): Promise<Batch>;
+    /** Starts a batch and waits until every grid is finished. */
+    run(params: CreateBatchParams, options?: RunOptions): Promise<Batch>;
+}
+declare class HistoryResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Every completed grid of the same map, oldest first, and the change between the first and the last. Free. */
+    get(params: HistoryParams, options?: RequestOptions): Promise<History>;
+}
+declare class Schedules {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Repeats a completed grid every week or every month. Each run costs the grid's credits. */
+    create(params: CreateScheduleParams, options?: RequestOptions): Promise<Schedule>;
+    list(options?: RequestOptions): Promise<ScheduleList>;
+    /** Pauses (`paused`) or resumes (`active`) a schedule. */
+    update(id: string, params: {
+        status: "active" | "paused";
+    }, options?: RequestOptions): Promise<Schedule>;
+    /** Stops repeating a grid for good. Grids already run are kept. Not retried: a lost response would turn into a 404. */
+    delete(id: string, options?: RequestOptions): Promise<Record<string, unknown>>;
+}
+declare class BalanceResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Credits left on the account (1 credit = 1 grid point). */
+    get(options?: RequestOptions): Promise<Balance>;
+}
+
+interface GeoGridAPIErrorOptions {
+    status?: number | null;
+    code?: string;
+    retryAfter?: number | null;
+    body?: unknown;
+    cause?: unknown;
+    gridId?: string;
+    batchId?: string;
+}
+declare class GeoGridAPIError extends Error {
+    /** HTTP status, `null` when no response was received. */
+    readonly status: number | null;
+    /** API error code (`invalid_body`, `insufficient_points`, `rate_limited`…). */
+    readonly code: string;
+    /** Seconds to wait before retrying, from the `Retry-After` header. */
+    readonly retryAfter: number | null;
+    /** Parsed error body, when there is one. */
+    readonly body: unknown;
+    /** Set when the error happened after a grid was created (while waiting for it): read it later with `grids.get`. */
+    gridId?: string;
+    /** Set when the error happened after a batch was created (while waiting for it): read it later with `batches.get`. */
+    batchId?: string;
+    constructor(message: string, options?: GeoGridAPIErrorOptions);
+}
+/** 400: invalid body or parameters. */
+declare class InvalidRequestError extends GeoGridAPIError {
+}
+/** 401: missing, malformed, unknown or revoked API key. */
+declare class AuthenticationError extends GeoGridAPIError {
+}
+/** 402: not enough credits for this grid or batch. */
+declare class InsufficientCreditsError extends GeoGridAPIError {
+}
+/** 404: unknown grid, batch or schedule, or no listing matches. */
+declare class NotFoundError extends GeoGridAPIError {
+}
+/** 409: conflicting state (grid not ready, already scheduled, idempotency key reused…). */
+declare class ConflictError extends GeoGridAPIError {
+}
+/** 422: an account limit is reached (`schedule_limit`). */
+declare class UnprocessableEntityError extends GeoGridAPIError {
+}
+/** 429: too many requests or too many grids still running. */
+declare class RateLimitError extends GeoGridAPIError {
+}
+/** 5xx: the API or the ranking engine is temporarily unavailable. */
+declare class APIError extends GeoGridAPIError {
+}
+/** No response: network failure or request timeout. */
+declare class APIConnectionError extends GeoGridAPIError {
+}
+/** A grid or batch did not finish within the wait timeout. It keeps running server side. */
+declare class WaitTimeoutError extends GeoGridAPIError {
+}
+
+declare const SIGNATURE_HEADER = "GeoGridAPI-Signature";
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+interface VerifyOptions {
+    /** Maximum age of the signature, in seconds (default 300). */
+    toleranceSeconds?: number;
+    /** Current time in unix seconds, for tests. */
+    now?: number;
+}
+/** Thrown by `constructEvent` when the signature is missing, invalid or too old. */
+declare class WebhookSignatureError extends GeoGridAPIError {
+}
+/**
+ * Checks the `GeoGridAPI-Signature` header of a webhook call.
+ * `payload` must be the raw request body, exactly as received (not re-serialized JSON).
+ */
+declare function verifyWebhookSignature(payload: string | Uint8Array, header: string | null | undefined, secret: string, options?: VerifyOptions): Promise<boolean>;
+/** Verifies the signature, then parses the event. Throws `WebhookSignatureError` when it does not match. */
+declare function constructEvent(payload: string | Uint8Array, header: string | null | undefined, secret: string, options?: VerifyOptions): Promise<WebhookEvent>;
+
+declare const VERSION = "0.1.0";
+
+/**
+ * GeoGridAPI client.
+ *
+ * ```ts
+ * import { GeoGridAPI } from "geogridapi";
+ * const gga = new GeoGridAPI(); // reads GEOGRIDAPI_API_KEY
+ * const grid = await gga.grids.run({ query: "Joe's Pizza, New York", keyword: "pizza", size: 7 });
+ * console.log(grid.summary?.average_rank, grid.ranks);
+ * ```
+ */
+declare class GeoGridAPI {
+    readonly places: Places;
+    readonly grids: Grids;
+    readonly batches: Batches;
+    readonly history: HistoryResource;
+    readonly schedules: Schedules;
+    readonly balance: BalanceResource;
+    private readonly transport;
+    constructor(options?: ClientOptions);
+    /** Whether the client uses a test key (`gga_test_`: free mock grids). */
+    get isTestKey(): boolean;
+}
+
+export { APIConnectionError, APIError, AuthenticationError, type Balance, type Batch, type BatchItem, type BatchItemStatus, type Center, type ClientOptions, type Competitor, ConflictError, type CreateBatchParams, type CreateGridParams, type CreateScheduleParams, DEFAULT_BASE_URL, DEFAULT_TOLERANCE_SECONDS, type Estimate, type FoundPlace, GeoGridAPI, GeoGridAPIError, type GeoGridAPIErrorOptions, type Grid, type GridDensity, type GridError, type GridFormat, type GridList, type GridPoint, type GridShape, type GridSize, type GridStatus, type GridSummary, type GridTarget, type History, type HistoryEntry, type HistoryParams, type IdempotentRequestOptions, InsufficientCreditsError, InvalidRequestError, type KeyMode, type ListGridsParams, NotFoundError, type Place, type PlaceList, type PlaceRef, type PreviousGrid, RateLimitError, type RequestOptions, type RunOptions, SIGNATURE_HEADER, type Schedule, type ScheduleList, type TopListing, UnprocessableEntityError, VERSION, type VerifyOptions, type WaitOptions, WaitTimeoutError, type WebhookEvent, type WebhookEventType, WebhookSignatureError, constructEvent, GeoGridAPI as default, verifyWebhookSignature };