deere-sdk 1.0.9 → 2.0.0

package/dist/api-servers.generated.js

@@ -0,0 +1,344 @@
+/**
+ * API server configuration per spec — single source of truth for URL resolution.
+ *
+ * @generated by scripts/generate-api-servers.ts — do not edit manually
+ * Last generated: 2026-04-13T20:34:18.775Z
+ *
+ * Env coverage matrix (X = supported, - = throws UnsupportedEnvironmentError):
+ *
+ *                              api  sandboxapi  partnerapi  apicert  apiqa.tal  partnerapicert  partnerapiqa  sandboxapiqa  apidev.tal
+ * aemp                          X    X           X           -        -          -               -             -             -
+ * assets                        X    X           X           X        X          -               -             -             -
+ * boundaries                    X    X           X           X        X          X               X             X             -
+ * clients                       X    X           X           X        X          -               -             -             -
+ * connection-management         X    X           -           X        X          -               -             -             -
+ * crop-types                    X    X           X           X        X          X               X             X             -
+ * equipment-measurement         X    -           X           X        X          X               X             X             -
+ * equipment                     X    -           X           -        -          -               -             -             -
+ * farms                         X    X           X           X        X          -               -             -             -
+ * field-operations-api          X    X           X           X        X          X               X             X             -
+ * fields                        X    X           X           X        X          -               -             -             -
+ * files                         X    X           X           X        X          X               X             X             X
+ * flags                         X    X           X           X        X          X               X             X             X
+ * guidance-lines                X    X           X           X        X          -               -             -             X
+ * harvest-id                    X    X           X           X        X          X               X             X             -
+ * machine-alerts                X    X           X           X        X          X               X             X             X
+ * machine-device-state-reports  X    X           X           X        X          -               -             -             -
+ * machine-engine-hours          X    X           X           X        X          -               -             -             -
+ * machine-hours-of-operation    X    X           X           X        X          -               -             -             -
+ * machine-locations             X    X           X           X        X          X               X             X             X
+ * map-layers                    X    X           X           X        X          -               -             -             -
+ * notifications                 X    X           X           X        X          X               X             X             X
+ * operators                     X    X           -           X        X          -               -             -             -
+ * organizations                 X    X           X           X        X          X               X             X             X
+ * partnerships                  X    X           X           X        X          X               X             X             X
+ * products                      X    X           X           X        X          -               -             -             X
+ * users                         X    X           X           X        X          -               -             -             -
+ * webhook                       X    X           X           X        X          -               -             -             X
+ *
+ * A dash (-) means the env is NOT supported for that spec. Calling a method
+ * on that API with that env throws UnsupportedEnvironmentError at request
+ * time, before any HTTP call — no silent cross-tier routing.
+ */
+export const KNOWN_ENVIRONMENTS = [
+    'api',
+    'sandboxapi',
+    'partnerapi',
+    'apicert',
+    'apiqa.tal',
+    'partnerapicert',
+    'partnerapiqa',
+    'sandboxapiqa',
+    'apidev.tal',
+];
+/**
+ * Default environment for new DeereClient instances when config.environment
+ * is not specified. 'sandboxapi' is safe-by-default — never silently hits
+ * production data.
+ */
+export const DEFAULT_ENVIRONMENT = 'sandboxapi';
+// ============================================================================
+// API_SERVERS — the resolver's lookup table, keyed by spec name
+// ============================================================================
+export const API_SERVERS = {
+    aemp: {
+        kind: 'static',
+        urlByEnvironment: {
+            api: 'https://partneraemp.deere.com',
+            partnerapi: 'https://partneraemp.deere.com',
+            sandboxapi: 'https://sandboxaemp.deere.com',
+        },
+    },
+    assets: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    boundaries: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'partnerapi',
+            'sandboxapi',
+            'apicert',
+            'partnerapicert',
+            'apiqa.tal',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    clients: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    'connection-management': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi'],
+    },
+    'crop-types': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'partnerapi',
+            'sandboxapi',
+            'apicert',
+            'partnerapicert',
+            'apiqa.tal',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    'equipment-measurement': {
+        kind: 'static',
+        urlByEnvironment: {
+            api: 'https://equipmentapi.deere.com/isg',
+            partnerapi: 'https://equipmentapi.deere.com/isg',
+            apicert: 'https://equipmentapi-cert.deere.com/isg',
+            partnerapicert: 'https://equipmentapi-cert.deere.com/isg',
+            'apiqa.tal': 'https://equipmentapi-qual.deere.com/isg',
+            partnerapiqa: 'https://equipmentapi-qual.deere.com/isg',
+            sandboxapiqa: 'https://equipmentapi-qual.deere.com/isg',
+        },
+    },
+    equipment: {
+        kind: 'static',
+        urlByEnvironment: {
+            api: 'https://equipmentapi.deere.com/isg',
+            partnerapi: 'https://equipmentapi.deere.com/isg',
+        },
+    },
+    farms: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    'field-operations-api': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'partnerapi',
+            'sandboxapi',
+            'apicert',
+            'partnerapicert',
+            'apiqa.tal',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    fields: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    files: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'sandboxapi',
+            'partnerapi',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'partnerapicert',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    flags: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'sandboxapi',
+            'partnerapi',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'partnerapicert',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    'guidance-lines': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'partnerapi',
+            'sandboxapi',
+            'api',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+        ],
+    },
+    'harvest-id': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'partnerapi',
+            'sandboxapi',
+            'apicert',
+            'partnerapicert',
+            'apiqa.tal',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    'machine-alerts': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'sandboxapi',
+            'partnerapi',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'partnerapicert',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    'machine-device-state-reports': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    'machine-engine-hours': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    'machine-hours-of-operation': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    'machine-locations': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'sandboxapi',
+            'partnerapi',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'partnerapicert',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    'map-layers': {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    notifications: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'sandboxapi',
+            'partnerapi',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'partnerapicert',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    operators: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi'],
+    },
+    organizations: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'sandboxapi',
+            'partnerapi',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'partnerapicert',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    partnerships: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'sandboxapi',
+            'partnerapi',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'partnerapicert',
+            'partnerapiqa',
+            'sandboxapiqa',
+        ],
+    },
+    products: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'partnerapi',
+            'sandboxapi',
+            'api',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+        ],
+    },
+    users: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: ['api', 'apicert', 'apiqa.tal', 'sandboxapi', 'partnerapi'],
+    },
+    webhook: {
+        kind: 'templated',
+        urlTemplate: 'https://{environment}.deere.com/platform',
+        supportedEnvironments: [
+            'api',
+            'apicert',
+            'apiqa.tal',
+            'apidev.tal',
+            'sandboxapi',
+            'partnerapi',
+        ],
+    },
+};
+//# sourceMappingURL=api-servers.generated.js.map

package/dist/api-servers.generated.js.map

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

package/dist/client.d.ts

@@ -2,16 +2,49 @@
  * John Deere API Client
  *
  * Unofficial TypeScript SDK for John Deere Operations Center API.
- * Provides typed access to all John Deere agricultural APIs.
+ *
+ * URL resolution flow (v2.0):
+ *
+ *   User code
+ *     │
+ *     ▼
+ *   deere.equipmentMeasurement.post(params)
+ *     │
+ *     ▼
+ *   this.client.post('equipment-measurement', '/orgs/.../measurements', data, options)
+ *     │
+ *     ▼
+ *   DeereClient.post()
+ *     ├─ resolveRequestUrl(spec, path, this.environment)
+ *     │    ├─ API_SERVERS[spec] lookup
+ *     │    ├─ templated   → urlTemplate.replace('{environment}', env)
+ *     │    ├─ static      → urlByEnvironment[env]  (throws UnsupportedEnvironmentError if missing)
+ *     │    └─ unavailable → throws NoServerConfigError
+ *     └─ requestUrl('POST', url, body, options)
+ *          └─ fetch(url, ...) with retry + timeout
+ *
+ * Absolute URLs bypass the resolver via fetchUrl() — used for HATEOAS next-page
+ * links and power-user escape hatches. fetchUrl attaches the Bearer token ONLY
+ * to *.deere.com hosts; third-party URLs get no Authorization header.
+ *
+ * URL data lives in src/api-servers.generated.ts, built from OpenAPI specs at
+ * build time by scripts/generate-api-servers.ts. Never hand-edit that file.
  */
-export type Environment = 'production' | 'sandbox' | 'partner' | 'cert' | 'qa';
+import { type Environment, type SpecName } from './api-servers.generated.js';
+export type { Environment, SpecName };
 export interface DeereClientConfig {
     /** OAuth access token */
     accessToken: string;
-    /** API environment. Defaults to 'sandbox' */
+    /**
+     * API environment — uses raw JD subdomain names. Defaults to 'sandboxapi'.
+     *
+     * Valid values: 'api' | 'sandboxapi' | 'partnerapi' | 'apicert' | 'apiqa.tal'
+     *             | 'partnerapicert' | 'partnerapiqa' | 'sandboxapiqa' | 'apidev.tal'
+     *
+     * Migration from v1: 'production' → 'api', 'sandbox' → 'sandboxapi',
+     * 'partner' → 'partnerapi', 'cert' → 'apicert', 'qa' → 'apiqa.tal'.
+     */
     environment?: Environment;
-    /** Custom base URL (overrides environment) */
-    baseUrl?: string;
     /** Custom fetch implementation */
     fetch?: typeof fetch;
     /** Default headers to include in all requests */
@@ -20,6 +53,15 @@ export interface DeereClientConfig {
     timeout?: number;
     /** Maximum number of retry attempts for failed requests. Defaults to 3. Set to 0 to disable retries. */
     maxRetries?: number;
+    /**
+     * Enable HATEOAS link traversal. When true, the client fetches parent resources
+     * and follows HAL links instead of constructing URLs directly.
+     * Required for John Deere production API certification.
+     * @default false
+     */
+    hateoas?: boolean;
+    /** Log HATEOAS resolution details to console for debugging. @default false */
+    hateoasDebug?: boolean;
 }
 export interface RetryConfig {
     /** Maximum number of retry attempts */
@@ -47,19 +89,8 @@ export interface Link {
     rel: string;
     uri: string;
 }
-export declare class DeereError extends Error {
-    readonly status: number;
-    readonly statusText: string;
-    readonly body?: unknown | undefined;
-    constructor(message: string, status: number, statusText: string, body?: unknown | undefined);
-}
-export declare class RateLimitError extends DeereError {
-    readonly retryAfter?: number | undefined;
-    constructor(message: string, status: number, statusText: string, retryAfter?: number | undefined, body?: unknown);
-}
-export declare class AuthError extends DeereError {
-    constructor(message: string, status: number, statusText: string, body?: unknown);
-}
+import { AuthError, DeereError, HateoasError, RateLimitError } from './errors.js';
+export { AuthError, DeereError, HateoasError, RateLimitError };
 /**
  * John Deere API Client
  *
@@ -67,11 +98,12 @@ export declare class AuthError extends DeereError {
  * ```typescript
  * const client = new DeereClient({
  *   accessToken: 'your-token',
- *   environment: 'sandbox',
+ *   environment: 'sandboxapi',  // v2: raw JD subdomain, not 'sandbox'
  *   maxRetries: 3, // Retries with exponential backoff (default: 3)
  * });
  *
- * const orgs = await client.get('/organizations');
+ * // v2: first arg is the spec name (generated classes do this for you)
+ * const orgs = await client.get('organizations', '/organizations');
  * ```
  *
  * @remarks
@@ -81,47 +113,101 @@ export declare class AuthError extends DeereError {
  * Set `maxRetries: 0` to disable automatic retries.
  */
 export declare class DeereClient {
-    private readonly baseUrl;
+    private readonly environment;
     private readonly accessToken;
     private readonly fetchFn;
     private readonly defaultHeaders;
     private readonly timeout;
     private readonly retryConfig;
+    private readonly hateoas;
+    private readonly hateoasDebug;
+    private readonly linkCache;
     constructor(config: DeereClientConfig);
     /**
-     * Make a GET request to the John Deere API
+     * Validates the environment string from config. Throws at construction
+     * time with a migration hint if the user passed a v1 friendly name or an
+     * unknown string — catches errors immediately instead of at first request.
      */
-    get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    private validateEnvironment;
     /**
-     * Make a POST request to the John Deere API
+     * GET request, spec-aware. Generated API classes call this with their own
+     * `spec` as the first argument — consumers don't normally call it directly.
      */
-    post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    get<T = unknown>(specName: SpecName, path: string, options?: RequestOptions): Promise<T>;
     /**
-     * Make a PUT request to the John Deere API
+     * POST request, spec-aware.
      */
-    put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    post<T = unknown>(specName: SpecName, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     /**
-     * Make a DELETE request to the John Deere API
+     * PUT request, spec-aware.
      */
-    delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+    put<T = unknown>(specName: SpecName, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
     /**
-     * Make a PATCH request to the John Deere API
+     * DELETE request, spec-aware.
      */
-    patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    delete<T = unknown>(specName: SpecName, path: string, options?: RequestOptions): Promise<T>;
     /**
-     * Follow a HAL link from a response
+     * PATCH request, spec-aware.
+     */
+    patch<T = unknown>(specName: SpecName, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Fetch an absolute URL directly. Escape hatch for HATEOAS next-page links,
+     * HAL link traversal, and power users with pre-resolved URLs.
+     *
+     * **Security**: Attaches the Bearer token ONLY when the target hostname
+     * matches a trusted `*.deere.com` origin. Third-party URLs get NO
+     * Authorization header — prevents accidental token leakage to tracking or
+     * proxy services. If you need to send auth to a non-JD host, set
+     * `Authorization` explicitly via `options.headers`.
+     */
+    fetchUrl<T = unknown>(method: string, url: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Follow a HAL link from a response. Accepts a Link object or a raw URL
+     * string. Delegates to fetchUrl() so the trusted-host check applies.
      */
     followLink<T = unknown>(link: Link | string, options?: RequestOptions): Promise<T>;
     /**
-     * Paginate through all results following nextPage links
+     * Paginate through all results following nextPage links. First page is
+     * resolved via the spec's URL config; subsequent pages use the absolute
+     * URLs returned by the API in `response.links`.
      */
-    paginate<T>(path: string, options?: RequestOptions): AsyncGenerator<T[], void, unknown>;
+    paginate<T>(specName: SpecName, path: string, options?: RequestOptions): AsyncGenerator<T[], void, unknown>;
     /**
-     * Get all items from a paginated endpoint
+     * Get all items from a paginated endpoint, spec-aware.
      */
-    getAll<T>(path: string, options?: RequestOptions): Promise<T[]>;
+    getAll<T>(specName: SpecName, path: string, options?: RequestOptions): Promise<T[]>;
     private request;
     private requestUrl;
+    /**
+     * Clear the HATEOAS link cache. Useful for long-lived clients or testing.
+     */
+    clearLinkCache(): void;
+    /**
+     * Pre-fetch parent resources to warm the HATEOAS link cache.
+     * Reduces latency for subsequent HATEOAS-resolved requests.
+     *
+     * @param specName - Spec that owns the paths (e.g. 'organizations')
+     * @param paths - Parent resource paths to pre-fetch (defaults to '/organizations')
+     */
+    warmLinkCache(specName: SpecName, paths?: string[]): Promise<void>;
+    /**
+     * Match a concrete path against the HATEOAS route map.
+     * Returns the concrete parent path, rel name, and optional parentSpec
+     * (which spec owns the parent resource — used for cross-spec HATEOAS).
+     * Returns null if no map entry matches.
+     */
+    private matchHateoasPattern;
+    /**
+     * Resolve a path via HATEOAS link traversal, spec-aware.
+     *
+     * Fetches the parent resource (via the parent's own spec host, not the
+     * child's — critical for cross-spec flows like equipment.yaml's org-scoped
+     * endpoints whose parent `/organizations/{orgId}` lives on the platform
+     * host, not equipmentapi.deere.com/isg).
+     *
+     * Throws HateoasError if resolution fails.
+     */
+    private resolveHateoasUrl;
     /**
      * Check if an error/status code is retryable
      */

package/dist/client.d.ts.map

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