@wherabouts/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,480 @@
+declare const WHERABOUTS_API_VERSION: "v1";
+declare const WHERABOUTS_SDK_VERSION: "0.2.0";
+/**
+ * Error codes the API may return. The server currently emits a subset; the full
+ * union is declared for forward-compatibility with the Phase 2 error envelope
+ * (see docs/CONTRACT.md §4). Unknown codes fall back to `unknown_error`.
+ */
+type WheraboutsErrorCode = "bad_request" | "conflict" | "forbidden" | "internal_error" | "not_found" | "rate_limited" | "timeout" | "unauthorized" | "unprocessable";
+interface WheraboutsFieldError {
+    message: string;
+    path: string;
+}
+interface WheraboutsApiErrorPayload {
+    error: {
+        code: WheraboutsErrorCode;
+        message: string;
+        /** Correlation id; also sent as the `X-Request-Id` response header. */
+        request_id?: string;
+        /** Link to documentation for this error code. */
+        doc_url?: string;
+        /** Field-level validation detail (validation errors only). */
+        fields?: WheraboutsFieldError[];
+    };
+}
+interface WheraboutsClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    /** Max automatic retries for transient failures. Default 2. */
+    maxRetries?: number;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+}
+/**
+ * Per-call overrides. Every resource method accepts an optional trailing
+ * `options` argument of this shape.
+ */
+interface CallOptions {
+    /** Extra headers merged over (not replacing) the client headers. */
+    headers?: Record<string, string>;
+    /** Idempotency key for write requests. Auto-generated on writes if omitted. */
+    idempotencyKey?: string;
+    /** Override the client's `maxRetries` for this call. */
+    maxRetries?: number;
+    /** Abort signal — aborting rejects the call (and is not retried). */
+    signal?: AbortSignal;
+    /** Override the client's `timeoutMs` for this call. */
+    timeoutMs?: number;
+}
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+interface RequestOptions extends CallOptions {
+    body?: unknown;
+    method: HttpMethod;
+    path: string;
+    query?: Record<string, number | string | undefined>;
+}
+type Requester = <T>(opts: RequestOptions) => Promise<T>;
+
+interface AddressSuggestion {
+    country: string;
+    formattedAddress: string;
+    id: number;
+    latitude: number;
+    locality: string;
+    longitude: number;
+    postcode: string;
+    state: string;
+    streetAddress: string;
+}
+interface AddressRecord {
+    buildingName: string | null;
+    confidence: number | null;
+    country: string;
+    flatNumber: string | null;
+    flatType: string | null;
+    gnafPid: string | null;
+    id: number;
+    latitude: number;
+    levelNumber: string | null;
+    levelType: string | null;
+    locality: string;
+    longitude: number;
+    numberFirst: string | null;
+    numberLast: string | null;
+    postcode: string;
+    state: string;
+    streetName: string;
+    streetSuffix: string | null;
+    streetType: string | null;
+}
+interface NearbyAddress {
+    buildingName: string | null;
+    country: string;
+    distance: number;
+    flatNumber: string | null;
+    flatType: string | null;
+    id: number;
+    latitude: number;
+    locality: string;
+    longitude: number;
+    numberFirst: string | null;
+    numberLast: string | null;
+    postcode: string;
+    state: string;
+    streetName: string;
+    streetType: string | null;
+}
+interface ReverseGeocodeAddress {
+    confidence: number | null;
+    country: string;
+    formattedAddress: string;
+    id: number;
+    latitude: number;
+    locality: string;
+    longitude: number;
+    postcode: string;
+    state: string;
+    streetAddress: string;
+}
+interface AutocompleteParams {
+    country?: string;
+    limit?: number;
+    q: string;
+    state?: string;
+}
+interface NearbyParams {
+    country?: string;
+    lat: number;
+    limit?: number;
+    lng: number;
+    radius?: number;
+}
+interface ReverseParams {
+    lat: number;
+    lng: number;
+}
+interface AutocompleteResponse {
+    count: number;
+    results: AddressSuggestion[];
+}
+interface NearbyResponse {
+    count: number;
+    query: {
+        lat: number;
+        lng: number;
+        radius: number;
+    };
+    results: NearbyAddress[];
+}
+interface ReverseResponse {
+    address: ReverseGeocodeAddress;
+    distance: number;
+    query: {
+        lat: number;
+        lng: number;
+    };
+}
+interface AddressesResource {
+    autocomplete(params: AutocompleteParams, options?: CallOptions): Promise<AutocompleteResponse>;
+    getById(id: number, options?: CallOptions): Promise<AddressRecord>;
+    nearby(params: NearbyParams, options?: CallOptions): Promise<NearbyResponse>;
+    reverse(params: ReverseParams, options?: CallOptions): Promise<ReverseResponse>;
+}
+declare const createAddresses: (request: Requester) => AddressesResource;
+
+interface BoundaryCrossing {
+    event: "entry" | "exit";
+    zoneId: number;
+    zoneName: string;
+}
+interface PushLocationBody {
+    lat: number;
+    lng: number;
+}
+interface PushLocationResponse {
+    crossings: BoundaryCrossing[];
+    zones: number[];
+}
+interface DeviceZonesResponse {
+    deviceId: string;
+    latitude: number | null;
+    longitude: number | null;
+    updatedAt: string | null;
+    zoneIds: number[];
+}
+interface DevicesResource {
+    pushLocation(deviceId: string, body: PushLocationBody, options?: CallOptions): Promise<PushLocationResponse>;
+    zones(deviceId: string, options?: CallOptions): Promise<DeviceZonesResponse>;
+}
+declare const createDevices: (request: Requester) => DevicesResource;
+
+/**
+ * Params for forward geocoding. Provide `q` for unstructured free-text search,
+ * OR `street` + `locality` (plus optional `state`, `postcode`, `country`) for
+ * structured mode. Set `structured: "true"` when using structured fields.
+ */
+interface ForwardGeocodeParams {
+    /** ISO 3166-1 alpha-2 country code, e.g. "AU". */
+    country?: string;
+    /** Suburb / locality (structured mode). */
+    locality?: string;
+    /** Postcode / ZIP. */
+    postcode?: string;
+    /** Free-text address query (unstructured mode). */
+    q?: string;
+    /** State abbreviation, e.g. "NSW". */
+    state?: string;
+    /** Street address (structured mode). */
+    street?: string;
+    /** Pass `"true"` to enable structured mode. */
+    structured?: "true" | "false";
+}
+interface GeocodeAddress {
+    country: string;
+    formattedAddress: string;
+    id: number;
+    latitude: number;
+    locality: string;
+    longitude: number;
+    postcode: string;
+    state: string;
+    streetAddress: string;
+}
+interface ForwardGeocodeResponse {
+    address: GeocodeAddress;
+    matchType: "structured" | "fuzzy";
+}
+interface BatchSubmitBody {
+    addresses: string[];
+}
+interface BatchSubmitResponse {
+    inputCount: number;
+    jobId: string;
+    status: "pending" | "processing";
+}
+interface BatchJobStatus {
+    completedAt: string | null;
+    downloadUrl: string | null;
+    error: string | null;
+    inputCount: number;
+    jobId: string;
+    processedCount: number | null;
+    status: "pending" | "processing" | "completed" | "failed";
+}
+interface BatchResultsResponse {
+    count: number;
+    results: unknown[];
+}
+interface GeocodeResource {
+    batch: {
+        submit(body: BatchSubmitBody, options?: CallOptions): Promise<BatchSubmitResponse>;
+        poll(jobId: string, options?: CallOptions): Promise<BatchJobStatus>;
+        results(jobId: string, options?: CallOptions): Promise<BatchResultsResponse>;
+    };
+    forward(params: ForwardGeocodeParams, options?: CallOptions): Promise<ForwardGeocodeResponse>;
+}
+declare const createGeocode: (request: Requester) => GeocodeResource;
+
+interface RegionsClassifyParams {
+    lat: number;
+    layers?: string;
+    lng: number;
+}
+interface RegionMatch {
+    code: string;
+    name: string;
+}
+interface RegionsClassifyResponse {
+    query: {
+        lat: number;
+        lng: number;
+    };
+    regions: Record<string, RegionMatch>;
+}
+interface RegionsResource {
+    classify(params: RegionsClassifyParams, options?: CallOptions): Promise<RegionsClassifyResponse>;
+}
+declare const createRegions: (request: Requester) => RegionsResource;
+
+interface DirectionsParams {
+    from?: string;
+    fromAddressId?: number;
+    profile?: "driving";
+    to?: string;
+    toAddressId?: number;
+}
+interface DirectionsGeometry {
+    coordinates: [number, number][];
+    type: "LineString";
+}
+interface DirectionsResponse {
+    distance_m: number;
+    duration_s: number;
+    geometry: DirectionsGeometry;
+    query: {
+        from: {
+            lat: number;
+            lng: number;
+        };
+        profile: string;
+        to: {
+            lat: number;
+            lng: number;
+        };
+    };
+}
+interface RoutingResource {
+    directions(params: DirectionsParams, options?: CallOptions): Promise<DirectionsResponse>;
+}
+declare const createRouting: (request: Requester) => RoutingResource;
+
+type WebhookEvent = "entry" | "exit";
+interface CreateWebhookBody {
+    events?: WebhookEvent[];
+    url: string;
+    zoneId?: number;
+}
+interface WebhookSubscription {
+    active: boolean;
+    createdAt: string;
+    events: WebhookEvent[];
+    id: number;
+    url: string;
+    zoneId: number | null;
+}
+interface CreateWebhookResponse extends WebhookSubscription {
+    secret: string;
+}
+interface WebhookListItem extends WebhookSubscription {
+    failing: boolean;
+}
+interface ListWebhooksResponse {
+    count: number;
+    results: WebhookListItem[];
+}
+interface DeleteWebhookResponse {
+    deleted: true;
+    id: number;
+}
+interface ReactivateWebhookResponse {
+    id: number;
+    reactivated: true;
+}
+interface WebhooksResource {
+    create(body: CreateWebhookBody, options?: CallOptions): Promise<CreateWebhookResponse>;
+    delete(id: number, options?: CallOptions): Promise<DeleteWebhookResponse>;
+    list(options?: CallOptions): Promise<ListWebhooksResponse>;
+    reactivate(id: number, options?: CallOptions): Promise<ReactivateWebhookResponse>;
+}
+declare const createWebhooks: (request: Requester) => WebhooksResource;
+
+interface ZoneRecord {
+    createdAt: string;
+    description: string | null;
+    id: number;
+    metadata: Record<string, unknown> | null;
+    name: string;
+    projectId: string;
+    updatedAt: string;
+}
+interface ZoneWithGeometry extends ZoneRecord {
+    geometry: {
+        type: string;
+        coordinates: number[][][];
+    };
+}
+interface GeoJsonPolygon {
+    coordinates: number[][][];
+    type: "Polygon";
+}
+interface ZoneListParams {
+    limit?: number;
+    page?: number;
+}
+interface ZoneContainsParams {
+    lat: number;
+    lng: number;
+}
+interface ZoneAddressesParams {
+    limit?: number;
+    page?: number;
+}
+interface ZoneCreateBody {
+    description?: string;
+    geometry: GeoJsonPolygon;
+    metadata?: Record<string, unknown>;
+    name: string;
+}
+interface ZoneUpdateBody {
+    description?: string;
+    geometry?: GeoJsonPolygon;
+    metadata?: Record<string, unknown>;
+    name?: string;
+}
+interface ZoneListResponse {
+    count: number;
+    page: number;
+    zones: ZoneRecord[];
+}
+interface ZoneDeleteResponse {
+    success: true;
+}
+interface ZoneContainsResponse {
+    count: number;
+    query: {
+        lat: number;
+        lng: number;
+    };
+    zones: ZoneRecord[];
+}
+interface ZoneAddressesResponse {
+    count: number;
+    query: {
+        id: number;
+        limit: number;
+        page: number;
+    };
+    results: Array<{
+        buildingName: string | null;
+        country: string;
+        flatNumber: string | null;
+        flatType: string | null;
+        id: number;
+        latitude: number;
+        locality: string;
+        longitude: number;
+        numberFirst: string | null;
+        numberLast: string | null;
+        postcode: string;
+        state: string;
+        streetName: string;
+        streetType: string | null;
+    }>;
+    truncated: boolean;
+}
+interface ZonesResource {
+    addresses(id: number, params?: ZoneAddressesParams, options?: CallOptions): Promise<ZoneAddressesResponse>;
+    contains(params: ZoneContainsParams, options?: CallOptions): Promise<ZoneContainsResponse>;
+    create(body: ZoneCreateBody, options?: CallOptions): Promise<ZoneRecord>;
+    delete(id: number, options?: CallOptions): Promise<ZoneDeleteResponse>;
+    get(id: number, options?: CallOptions): Promise<ZoneWithGeometry>;
+    list(params?: ZoneListParams, options?: CallOptions): Promise<ZoneListResponse>;
+    update(id: number, body: ZoneUpdateBody, options?: CallOptions): Promise<ZoneRecord>;
+}
+declare const createZones: (request: Requester) => ZonesResource;
+
+interface WheraboutsClient {
+    addresses: AddressesResource;
+    devices: DevicesResource;
+    geocode: GeocodeResource;
+    regions: RegionsResource;
+    routing: RoutingResource;
+    webhooks: WebhooksResource;
+    zones: ZonesResource;
+}
+declare const createWheraboutsClient: (config: WheraboutsClientConfig) => WheraboutsClient;
+
+declare class WheraboutsApiError extends Error {
+    readonly code: WheraboutsErrorCode | "unknown_error";
+    readonly payload: WheraboutsApiErrorPayload | null;
+    readonly status: number;
+    /** Correlation id from the `X-Request-Id` header or error body, if present. */
+    readonly requestId: string | null;
+    /** Documentation link for this error, if the API provided one. */
+    readonly docUrl: string | null;
+    /** Field-level validation detail, if the API provided any. */
+    readonly fields: WheraboutsFieldError[] | null;
+    constructor(options: {
+        code?: WheraboutsApiError["code"];
+        docUrl?: string | null;
+        fields?: WheraboutsFieldError[] | null;
+        message: string;
+        payload?: WheraboutsApiErrorPayload | null;
+        requestId?: string | null;
+        status: number;
+    });
+}
+
+export { type AddressRecord, type AddressSuggestion, type AddressesResource, type AutocompleteParams, type AutocompleteResponse, type BatchJobStatus, type BatchResultsResponse, type BatchSubmitBody, type BatchSubmitResponse, type BoundaryCrossing, type CallOptions, type CreateWebhookBody, type CreateWebhookResponse, type DeleteWebhookResponse, type DeviceZonesResponse, type DevicesResource, type DirectionsGeometry, type DirectionsParams, type DirectionsResponse, type ForwardGeocodeParams, type ForwardGeocodeResponse, type GeoJsonPolygon, type GeocodeAddress, type GeocodeResource, type ListWebhooksResponse, type NearbyAddress, type NearbyParams, type NearbyResponse, type PushLocationBody, type PushLocationResponse, type ReactivateWebhookResponse, type RegionMatch, type RegionsClassifyParams, type RegionsClassifyResponse, type RegionsResource, type ReverseGeocodeAddress, type ReverseParams, type ReverseResponse, type RoutingResource, WHERABOUTS_API_VERSION, WHERABOUTS_SDK_VERSION, type WebhookEvent, type WebhookListItem, type WebhookSubscription, type WebhooksResource, WheraboutsApiError, type WheraboutsApiErrorPayload, type WheraboutsClient, type WheraboutsClientConfig, type WheraboutsErrorCode, type WheraboutsFieldError, type ZoneAddressesParams, type ZoneAddressesResponse, type ZoneContainsParams, type ZoneContainsResponse, type ZoneCreateBody, type ZoneDeleteResponse, type ZoneListParams, type ZoneListResponse, type ZoneRecord, type ZoneUpdateBody, type ZoneWithGeometry, type ZonesResource, createAddresses, createDevices, createGeocode, createRegions, createRouting, createWebhooks, createWheraboutsClient, createZones };