deere-sdk 1.0.10 → 2.1.0

package/dist/environment-resolver.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Runtime URL resolver for spec-aware requests.
+ *
+ * Pure, deterministic, and side-effect-free. Every DeereClient request goes
+ * through `resolveRequestUrl` to turn a (spec, path, environment) tuple into
+ * a full URL — or throw a clear, actionable error before any HTTP call.
+ *
+ * Design note: no heuristics, no silent fallbacks. If the spec's static map
+ * doesn't cover the current environment, we throw. Sandbox vs prod is a
+ * trust boundary — falling back silently could delete customer data.
+ */
+import { type Environment, type SpecName } from './api-servers.generated.js';
+import { DeereError } from './errors.js';
+/**
+ * Thrown when a spec has no server configuration (missing/malformed
+ * servers block, or generator classified it as 'unavailable').
+ */
+export declare class NoServerConfigError extends DeereError {
+    constructor(specName: string, reason?: string);
+}
+/**
+ * Thrown when a spec is available but does not support the requested
+ * environment. The error message lists supported envs + concrete alternatives.
+ */
+export declare class UnsupportedEnvironmentError extends DeereError {
+    constructor(specName: string, environment: string, supported: readonly string[]);
+}
+/**
+ * Resolves a request URL for the given spec and environment.
+ *
+ * @param specName  Name of the OpenAPI spec (e.g. 'equipment', 'organizations').
+ * @param path      Relative path starting with '/' or '?' (generated code always emits this).
+ * @param environment  Environment from the DeereClient config.
+ * @returns The full URL ready for `fetch`.
+ * @throws NoServerConfigError if the spec isn't in API_SERVERS or is unavailable.
+ * @throws UnsupportedEnvironmentError if the spec is static and the env isn't in its map.
+ * @throws Error if the path doesn't start with '/' or '?' (developer error guard).
+ */
+export declare function resolveRequestUrl(specName: SpecName | string, path: string, environment: Environment): string;
+//# sourceMappingURL=environment-resolver.d.ts.map

package/dist/environment-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-resolver.d.ts","sourceRoot":"","sources":["../src/environment-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAe,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAC1F,OAAO,EAAuB,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9D;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAY9C;AAED;;;GAGG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;gBAC7C,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE;CAchF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAC3B,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,WAAW,GACvB,MAAM,CAmCR"}

package/dist/environment-resolver.js

@@ -0,0 +1,79 @@
+/**
+ * Runtime URL resolver for spec-aware requests.
+ *
+ * Pure, deterministic, and side-effect-free. Every DeereClient request goes
+ * through `resolveRequestUrl` to turn a (spec, path, environment) tuple into
+ * a full URL — or throw a clear, actionable error before any HTTP call.
+ *
+ * Design note: no heuristics, no silent fallbacks. If the spec's static map
+ * doesn't cover the current environment, we throw. Sandbox vs prod is a
+ * trust boundary — falling back silently could delete customer data.
+ */
+import { API_SERVERS } from './api-servers.generated.js';
+import { CLIENT_ERROR_STATUS, DeereError } from './errors.js';
+/**
+ * Thrown when a spec has no server configuration (missing/malformed
+ * servers block, or generator classified it as 'unavailable').
+ */
+export class NoServerConfigError extends DeereError {
+    constructor(specName, reason) {
+        super(`Spec '${specName}' has no server configuration.${reason
+            ? ` ${reason}`
+            : " Its OpenAPI file is missing a 'servers' block or has a malformed URL."}`, CLIENT_ERROR_STATUS, 'NoServerConfig');
+        this.name = 'NoServerConfigError';
+    }
+}
+/**
+ * Thrown when a spec is available but does not support the requested
+ * environment. The error message lists supported envs + concrete alternatives.
+ */
+export class UnsupportedEnvironmentError extends DeereError {
+    constructor(specName, environment, supported) {
+        const supportedList = supported.length > 0 ? supported.join(', ') : '(none)';
+        super(`The '${specName}' API does not support environment '${environment}'.\n\n` +
+            `Supported environments for this spec: ${supportedList}.\n\n` +
+            `This usually means the underlying JD backend has a different tier ` +
+            `structure than the platform APIs (the ISG proxy uses qual/cert/prod ` +
+            `tiers, with no sandbox or dev tier). For testing, try environment ` +
+            `'apiqa.tal' (qual tier). For production, use 'api' (prod tier).`, CLIENT_ERROR_STATUS, 'UnsupportedEnvironment');
+        this.name = 'UnsupportedEnvironmentError';
+    }
+}
+/**
+ * Resolves a request URL for the given spec and environment.
+ *
+ * @param specName  Name of the OpenAPI spec (e.g. 'equipment', 'organizations').
+ * @param path      Relative path starting with '/' or '?' (generated code always emits this).
+ * @param environment  Environment from the DeereClient config.
+ * @returns The full URL ready for `fetch`.
+ * @throws NoServerConfigError if the spec isn't in API_SERVERS or is unavailable.
+ * @throws UnsupportedEnvironmentError if the spec is static and the env isn't in its map.
+ * @throws Error if the path doesn't start with '/' or '?' (developer error guard).
+ */
+export function resolveRequestUrl(specName, path, environment) {
+    // Defensive invariant: generated code always emits paths with a leading '/'.
+    // This guard catches manual callers passing `client.get('spec', 'relative')`
+    // by mistake, turning a silent 404 on `host+relative` into a clear error.
+    if (path && !path.startsWith('/') && !path.startsWith('?')) {
+        throw new Error(`Invalid path '${path}': must start with '/' (e.g., '/organizations') ` +
+            `or '?' for query-only paths.`);
+    }
+    const config = API_SERVERS[specName];
+    if (!config) {
+        throw new NoServerConfigError(specName);
+    }
+    if (config.kind === 'unavailable') {
+        throw new NoServerConfigError(specName, config.reason);
+    }
+    if (config.kind === 'templated') {
+        const baseUrl = config.urlTemplate.replace('{environment}', environment);
+        return `${baseUrl}${path}`;
+    }
+    // kind === 'static' — partial map, throw on unsupported env
+    const baseUrl = config.urlByEnvironment[environment];
+    if (!baseUrl) {
+        throw new UnsupportedEnvironmentError(specName, environment, Object.keys(config.urlByEnvironment));
+    }
+    return `${baseUrl}${path}`;
+}
+//# sourceMappingURL=environment-resolver.js.map

package/dist/environment-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment-resolver.js","sourceRoot":"","sources":["../src/environment-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAmC,MAAM,4BAA4B,CAAC;AAC1F,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9D;;;GAGG;AACH,MAAM,OAAO,mBAAoB,SAAQ,UAAU;IACjD,YAAY,QAAgB,EAAE,MAAe;QAC3C,KAAK,CACH,SAAS,QAAQ,iCACf,MAAM;YACJ,CAAC,CAAC,IAAI,MAAM,EAAE;YACd,CAAC,CAAC,wEACN,EAAE,EACF,mBAAmB,EACnB,gBAAgB,CACjB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,2BAA4B,SAAQ,UAAU;IACzD,YAAY,QAAgB,EAAE,WAAmB,EAAE,SAA4B;QAC7E,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC7E,KAAK,CACH,QAAQ,QAAQ,uCAAuC,WAAW,QAAQ;YACxE,yCAAyC,aAAa,OAAO;YAC7D,oEAAoE;YACpE,sEAAsE;YACtE,oEAAoE;YACpE,iEAAiE,EACnE,mBAAmB,EACnB,wBAAwB,CACzB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAA2B,EAC3B,IAAY,EACZ,WAAwB;IAExB,6EAA6E;IAC7E,6EAA6E;IAC7E,0EAA0E;IAC1E,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,kDAAkD;YACrE,8BAA8B,CACjC,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,QAAoB,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QAClC,MAAM,IAAI,mBAAmB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,eAAe,EAAE,WAAW,CAAC,CAAC;QACzE,OAAO,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,4DAA4D;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAC,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACrD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,2BAA2B,CACnC,QAAQ,EACR,WAAW,EACX,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,CACrC,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC;AAC7B,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Error hierarchy for deere-sdk.
+ *
+ * Lives in a separate file from client.ts to avoid a circular import with
+ * environment-resolver.ts (which needs DeereError to build its own
+ * NoServerConfigError and UnsupportedEnvironmentError).
+ *
+ * client.ts re-exports everything here for backward compatibility with any
+ * consumer that imports these classes from 'deere-sdk' main entry.
+ */
+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);
+}
+export declare class HateoasError extends Error {
+    readonly path: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, path: string, cause?: Error | undefined);
+}
+/**
+ * Sentinel status for client-side errors that were never sent over HTTP.
+ * Distinct from HTTP 0 (which requestUrl uses for timeouts), so the retry
+ * logic in requestUrl that checks `error.status === 0 && error.statusText ===
+ * 'Timeout'` never fires for config/resolver errors.
+ */
+export declare const CLIENT_ERROR_STATUS = -1;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAa,UAAW,SAAQ,KAAK;aAGjB,MAAM,EAAE,MAAM;aACd,UAAU,EAAE,MAAM;aAClB,IAAI,CAAC,EAAE,OAAO;gBAH9B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,OAAO,YAAA;CAKjC;AAED,qBAAa,cAAe,SAAQ,UAAU;aAK1B,UAAU,CAAC,EAAE,MAAM;gBAHnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EACF,UAAU,CAAC,EAAE,MAAM,YAAA,EACnC,IAAI,CAAC,EAAE,OAAO;CAKjB;AAED,qBAAa,SAAU,SAAQ,UAAU;gBAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAIhF;AAED,qBAAa,YAAa,SAAQ,KAAK;aAGnB,IAAI,EAAE,MAAM;aACZ,KAAK,CAAC,EAAE,KAAK;gBAF7B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,KAAK,YAAA;CAKhC;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC"}

package/dist/errors.js

@@ -0,0 +1,54 @@
+/**
+ * Error hierarchy for deere-sdk.
+ *
+ * Lives in a separate file from client.ts to avoid a circular import with
+ * environment-resolver.ts (which needs DeereError to build its own
+ * NoServerConfigError and UnsupportedEnvironmentError).
+ *
+ * client.ts re-exports everything here for backward compatibility with any
+ * consumer that imports these classes from 'deere-sdk' main entry.
+ */
+export class DeereError extends Error {
+    status;
+    statusText;
+    body;
+    constructor(message, status, statusText, body) {
+        super(message);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.name = 'DeereError';
+    }
+}
+export class RateLimitError extends DeereError {
+    retryAfter;
+    constructor(message, status, statusText, retryAfter, body) {
+        super(message, status, statusText, body);
+        this.retryAfter = retryAfter;
+        this.name = 'RateLimitError';
+    }
+}
+export class AuthError extends DeereError {
+    constructor(message, status, statusText, body) {
+        super(message, status, statusText, body);
+        this.name = 'AuthError';
+    }
+}
+export class HateoasError extends Error {
+    path;
+    cause;
+    constructor(message, path, cause) {
+        super(message);
+        this.path = path;
+        this.cause = cause;
+        this.name = 'HateoasError';
+    }
+}
+/**
+ * Sentinel status for client-side errors that were never sent over HTTP.
+ * Distinct from HTTP 0 (which requestUrl uses for timeouts), so the retry
+ * logic in requestUrl that checks `error.status === 0 && error.statusText ===
+ * 'Timeout'` never fires for config/resolver errors.
+ */
+export const CLIENT_ERROR_STATUS = -1;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,OAAO,UAAW,SAAQ,KAAK;IAGjB;IACA;IACA;IAJlB,YACE,OAAe,EACC,MAAc,EACd,UAAkB,EAClB,IAAc;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAClB,SAAI,GAAJ,IAAI,CAAU;QAG9B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,UAAU;IAK1B;IAJlB,YACE,OAAe,EACf,MAAc,EACd,UAAkB,EACF,UAAmB,EACnC,IAAc;QAEd,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;QAHzB,eAAU,GAAV,UAAU,CAAS;QAInC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,SAAU,SAAQ,UAAU;IACvC,YAAY,OAAe,EAAE,MAAc,EAAE,UAAkB,EAAE,IAAc;QAC7E,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,KAAK;IAGnB;IACA;IAHlB,YACE,OAAe,EACC,IAAY,EACZ,KAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAQ;QAG7B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,CAAC"}

package/dist/hateoas-map.d.ts

@@ -6,11 +6,20 @@
  *
  * @generated by generate-sdk.ts — do not edit manually
  */
+import type { SpecName } from './api-servers.generated.js';
 export interface HateoasRoute {
     /** Path pattern of the parent resource (with parameter placeholders) */
     parentPath: string;
     /** HAL link relation name to follow from the parent response */
     rel: string;
+    /**
+     * Which OpenAPI spec declares the parent resource. Required for cross-spec
+     * HATEOAS: if a child lives in equipment.yaml but its parent
+     * /organizations/{orgId} is declared in organizations.yaml, the client
+     * must fetch the parent via organizations.yaml's host (platform) not
+     * equipment.yaml's host (equipmentapi.deere.com/isg).
+     */
+    parentSpec: SpecName;
 }
 export declare const HATEOAS_MAP: Record<string, HateoasRoute>;
 //# sourceMappingURL=hateoas-map.d.ts.map

package/dist/hateoas-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hateoas-map.d.ts","sourceRoot":"","sources":["../src/hateoas-map.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAuHpD,CAAC"}
+{"version":3,"file":"hateoas-map.d.ts","sourceRoot":"","sources":["../src/hateoas-map.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,UAAU,EAAE,QAAQ,CAAC;CACtB;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAsKpD,CAAC"}

package/dist/hateoas-map.js

@@ -7,123 +7,170 @@
  * @generated by generate-sdk.ts — do not edit manually
  */
 export const HATEOAS_MAP = {
-    '/assets/{assetId}/locations': { parentPath: '/assets/{assetId}', rel: 'locations' },
+    '/assets/{assetId}/locations': {
+        parentPath: '/assets/{assetId}',
+        rel: 'locations',
+        parentSpec: 'assets',
+    },
     '/equipmentMakes/{equipmentMakeId}/equipmentISGTypes': {
         parentPath: '/equipmentMakes/{equipmentMakeId}',
         rel: 'equipmentISGTypes',
+        parentSpec: 'equipment',
     },
     '/equipmentMakes/{equipmentMakeId}/equipmentISGTypes/{equipmentISGTypeId}/equipmentModels': {
         parentPath: '/equipmentMakes/{equipmentMakeId}/equipmentISGTypes/{equipmentISGTypeId}',
         rel: 'equipmentModels',
+        parentSpec: 'equipment',
     },
     '/equipmentMakes/{equipmentMakeId}/equipmentTypes': {
         parentPath: '/equipmentMakes/{equipmentMakeId}',
         rel: 'equipmentTypes',
+        parentSpec: 'equipment',
     },
     '/fieldOperations/{operationId}/boundary': {
         parentPath: '/fieldOperations/{operationId}',
         rel: 'boundary',
-    },
-    '/machines/{principalId}/alerts': { parentPath: '/machines/{principalId}', rel: 'alerts' },
-    '/machines/{principalId}/deviceStateReports': {
-        parentPath: '/machines/{principalId}',
-        rel: 'deviceStateReports',
-    },
-    '/machines/{principalId}/engineHours': {
-        parentPath: '/machines/{principalId}',
-        rel: 'engineHours',
-    },
-    '/machines/{principalId}/hoursOfOperation': {
-        parentPath: '/machines/{principalId}',
-        rel: 'hoursOfOperation',
-    },
-    '/machines/{principalId}/locationHistory': {
-        parentPath: '/machines/{principalId}',
-        rel: 'locationHistory',
+        parentSpec: 'field-operations-api',
     },
     '/organizations/{organizationId}/cropTypes': {
         parentPath: '/organizations/{organizationId}',
         rel: 'cropTypes',
+        parentSpec: 'organizations',
     },
     '/organizations/{organizationId}/equipment': {
         parentPath: '/organizations/{organizationId}',
         rel: 'equipment',
-    },
-    '/organizations/{organizationId}/equipment/{principalId}/measurements': {
-        parentPath: '/organizations/{organizationId}/equipment/{principalId}',
-        rel: 'measurements',
+        parentSpec: 'organizations',
     },
     '/organizations/{organizationId}/varieties': {
         parentPath: '/organizations/{organizationId}',
         rel: 'varieties',
+        parentSpec: 'organizations',
+    },
+    '/organizations/{orgId}/assets': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'assets',
+        parentSpec: 'organizations',
+    },
+    '/organizations/{orgId}/boundaries': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'boundaries',
+        parentSpec: 'organizations',
+    },
+    '/organizations/{orgId}/clients': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'clients',
+        parentSpec: 'organizations',
     },
-    '/organizations/{orgId}/assets': { parentPath: '/organizations/{orgId}', rel: 'assets' },
-    '/organizations/{orgId}/boundaries': { parentPath: '/organizations/{orgId}', rel: 'boundaries' },
-    '/organizations/{orgId}/clients': { parentPath: '/organizations/{orgId}', rel: 'clients' },
     '/organizations/{orgId}/clients/{id}/farms': {
         parentPath: '/organizations/{orgId}/clients/{id}',
         rel: 'farms',
+        parentSpec: 'clients',
     },
     '/organizations/{orgID}/clients/{id}/fields': {
         parentPath: '/organizations/{orgID}/clients/{id}',
         rel: 'fields',
+        parentSpec: 'clients',
     },
     '/organizations/{orgId}/connections': {
         parentPath: '/organizations/{orgId}',
         rel: 'connections',
+        parentSpec: 'organizations',
+    },
+    '/organizations/{orgId}/farms': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'farms',
+        parentSpec: 'organizations',
     },
-    '/organizations/{orgId}/farms': { parentPath: '/organizations/{orgId}', rel: 'farms' },
     '/organizations/{orgId}/farms/{farmId}/clients': {
         parentPath: '/organizations/{orgId}/farms/{farmId}',
         rel: 'clients',
+        parentSpec: 'farms',
     },
     '/organizations/{orgID}/farms/{id}/fields': {
         parentPath: '/organizations/{orgID}/farms/{id}',
         rel: 'fields',
+        parentSpec: 'farms',
+    },
+    '/organizations/{orgId}/fields': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'fields',
+        parentSpec: 'organizations',
     },
-    '/organizations/{orgId}/fields': { parentPath: '/organizations/{orgId}', rel: 'fields' },
     '/organizations/{orgId}/fields/{fieldId}/boundaries': {
         parentPath: '/organizations/{orgId}/fields/{fieldId}',
         rel: 'boundaries',
+        parentSpec: 'fields',
     },
     '/organizations/{orgId}/fields/{fieldId}/farms': {
         parentPath: '/organizations/{orgId}/fields/{fieldId}',
         rel: 'farms',
+        parentSpec: 'fields',
     },
     '/organizations/{orgId}/fields/{fieldId}/fieldOperations': {
         parentPath: '/organizations/{orgId}/fields/{fieldId}',
         rel: 'fieldOperations',
+        parentSpec: 'fields',
     },
     '/organizations/{orgId}/fields/{fieldId}/flags': {
         parentPath: '/organizations/{orgId}/fields/{fieldId}',
         rel: 'flags',
+        parentSpec: 'fields',
     },
     '/organizations/{orgId}/fields/{fieldId}/guidanceLines': {
         parentPath: '/organizations/{orgId}/fields/{fieldId}',
         rel: 'guidanceLines',
+        parentSpec: 'fields',
     },
     '/organizations/{orgID}/fields/{id}/clients': {
         parentPath: '/organizations/{orgID}/fields/{id}',
         rel: 'clients',
+        parentSpec: 'fields',
     },
     '/organizations/{orgId}/fields/{id}/mapLayerSummaries': {
         parentPath: '/organizations/{orgId}/fields/{id}',
         rel: 'mapLayerSummaries',
+        parentSpec: 'fields',
+    },
+    '/organizations/{orgId}/files': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'files',
+        parentSpec: 'organizations',
+    },
+    '/organizations/{orgId}/flags': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'flags',
+        parentSpec: 'organizations',
     },
-    '/organizations/{orgId}/files': { parentPath: '/organizations/{orgId}', rel: 'files' },
-    '/organizations/{orgId}/flags': { parentPath: '/organizations/{orgId}', rel: 'flags' },
     '/organizations/{orgId}/harvestIdentificationModules': {
         parentPath: '/organizations/{orgId}',
         rel: 'harvestIdentificationModules',
+        parentSpec: 'organizations',
+    },
+    '/organizations/{orgId}/operators': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'operators',
+        parentSpec: 'organizations',
+    },
+    '/organizations/{orgId}/users': {
+        parentPath: '/organizations/{orgId}',
+        rel: 'users',
+        parentSpec: 'organizations',
+    },
+    '/partnerships/{token}/permissions': {
+        parentPath: '/partnerships/{token}',
+        rel: 'permissions',
+        parentSpec: 'partnerships',
+    },
+    '/users/{userName}/organizations': {
+        parentPath: '/users/{userName}',
+        rel: 'organizations',
+        parentSpec: 'users',
     },
-    '/organizations/{orgId}/notifications/events': {
-        parentPath: '/organizations/{orgId}/notifications',
-        rel: 'events',
+    '/varieties/{erid}/documents': {
+        parentPath: '/varieties/{erid}',
+        rel: 'documents',
+        parentSpec: 'products',
     },
-    '/organizations/{orgId}/operators': { parentPath: '/organizations/{orgId}', rel: 'operators' },
-    '/organizations/{orgId}/users': { parentPath: '/organizations/{orgId}', rel: 'users' },
-    '/partnerships/{token}/permissions': { parentPath: '/partnerships/{token}', rel: 'permissions' },
-    '/users/{userName}/organizations': { parentPath: '/users/{userName}', rel: 'organizations' },
-    '/varieties/{erid}/documents': { parentPath: '/varieties/{erid}', rel: 'documents' },
 };
 //# sourceMappingURL=hateoas-map.js.map

package/dist/hateoas-map.js.map

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

package/dist/index.d.ts

@@ -32,5 +32,6 @@ export * from './api/index.js';
 export type { DeereClientConfig, Environment, Link, PaginatedResponse, RequestOptions, } from './client.js';
 export { AuthError, createClient, DeereClient, DeereError, HateoasError, RateLimitError, } from './client.js';
 export { createDeere, Deere } from './deere.js';
+export { type FieldOperationWithMeasurements, SafeFacades, SafeFieldOperationsApi, } from './safe/index.js';
 export * as Types from './types/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,IAAI,EACJ,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGhD,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,IAAI,EACJ,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAIhD,OAAO,EACL,KAAK,8BAA8B,EACnC,WAAW,EACX,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -34,6 +34,9 @@ export * from './api/index.js';
 export { AuthError, createClient, DeereClient, DeereError, HateoasError, RateLimitError, } from './client.js';
 // Main SDK class
 export { createDeere, Deere } from './deere.js';
+// Safe facades that force query params the raw API leaves optional.
+// See scripts/embed-contracts.yaml and src/safe/ for context.
+export { SafeFacades, SafeFieldOperationsApi, } from './safe/index.js';
 // OpenAPI Types (for advanced usage)
 export * as Types from './types/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,cAAc;AACd,cAAc,gBAAgB,CAAC;AAQ/B,mBAAmB;AACnB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEhD,qCAAqC;AACrC,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,cAAc;AACd,cAAc,gBAAgB,CAAC;AAQ/B,mBAAmB;AACnB,OAAO,EACL,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,iBAAiB;AACjB,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEhD,oEAAoE;AACpE,8DAA8D;AAC9D,OAAO,EAEL,WAAW,EACX,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAEzB,qCAAqC;AACrC,OAAO,KAAK,KAAK,MAAM,kBAAkB,CAAC"}

package/dist/safe/field-operations.d.ts

@@ -0,0 +1,73 @@
+/**
+ * SafeFieldOperationsApi — hand-written facade over the generated
+ * FieldOperationsApi.
+ *
+ * The raw FieldOperationsApi.listAll() takes an optional embed param. John
+ * Deere's API silently omits the measurementTypes array on returned
+ * FieldOperation objects unless the request passes ?embed=measurementTypes,
+ * and JD's OpenAPI spec never encodes that invariant. Three separate times in
+ * FieldMCP, developers called listAll without the embed param and shipped
+ * placeholder zeros to production because the downstream normalizer couldn't
+ * distinguish "missing data" from "real zero." The safe wrapper makes the
+ * forcing function syntactic: you can't call listAllWithMeasurements without
+ * the embed param, because the wrapper adds it for you.
+ *
+ * See scripts/embed-contracts.yaml for the contract registry that makes the
+ * narrowed type (measurementTypes non-optional) honest at the type level.
+ */
+import type { FieldOperationsApi } from '../api/field-operations-api.js';
+import type { components } from '../types/generated/field-operations-api.js';
+type RawFieldOperation = components['schemas']['FieldOperation'];
+type FieldOperationMeasurement = components['schemas']['FieldOperationMeasurement'];
+/**
+ * A FieldOperation guaranteed to carry its measurementTypes array.
+ *
+ * The raw `FieldOperation` type marks `measurementTypes` as optional because
+ * JD's API populates it only when `?embed=measurementTypes` is passed.
+ * `SafeFieldOperationsApi.listAllWithMeasurements()` forces the embed param
+ * AND verifies every returned operation actually carries the array (throwing
+ * `DeereError` on contract violation), so the narrowed type is honest, not
+ * a cast over a possible `undefined`.
+ *
+ * An empty `measurementTypes: []` is valid (operation exists but has no
+ * recorded measurements yet). `undefined` is a contract violation and throws.
+ */
+export type FieldOperationWithMeasurements = RawFieldOperation & {
+    measurementTypes: FieldOperationMeasurement[];
+};
+type RawListAllParams = NonNullable<Parameters<FieldOperationsApi['listAll']>[2]>;
+type SafeListAllParams = Omit<RawListAllParams, 'embed'>;
+export declare class SafeFieldOperationsApi {
+    private readonly raw;
+    constructor(raw: FieldOperationsApi);
+    /**
+     * List all field operations on a field with measurement data embedded.
+     *
+     * Forces `embed=measurementTypes` on the outgoing request, so yield, area,
+     * moisture, application rate, and seeding population are guaranteed present
+     * where JD has recorded them. Empty `measurementTypes: []` is a valid
+     * response (JD has no measurements for that operation yet). `undefined`
+     * `measurementTypes` on any returned operation is treated as a contract
+     * violation and throws `DeereError` naming the offending operation id.
+     *
+     * Prefer this over `deere.fieldOperations.listAll` when your code reads
+     * yield, rate, or any other field under `measurementTypes`. The raw method
+     * silently returns FieldOperation objects with `measurementTypes` omitted
+     * unless the caller remembers to pass the embed param, and has caused
+     * production bugs in FieldMCP three separate times.
+     *
+     * @param orgId  The John Deere organization id.
+     * @param fieldId  The field id within that organization.
+     * @param params  Optional filter params (cropSeason, fieldOperationType,
+     *                date range, workPlanIds). Any `embed` value in params is
+     *                ignored — the wrapper always overrides with
+     *                `embed: 'measurementTypes'`.
+     * @throws {DeereError} If JD returns any operation without a
+     *                     `measurementTypes` array despite the embed param
+     *                     being passed. This indicates JD's wire format has
+     *                     drifted from the documented contract.
+     */
+    listAllWithMeasurements(orgId: string, fieldId: string, params?: SafeListAllParams): Promise<FieldOperationWithMeasurements[]>;
+}
+export {};
+//# sourceMappingURL=field-operations.d.ts.map

package/dist/safe/field-operations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-operations.d.ts","sourceRoot":"","sources":["../../src/safe/field-operations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4CAA4C,CAAC;AAE7E,KAAK,iBAAiB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,gBAAgB,CAAC,CAAC;AACjE,KAAK,yBAAyB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AAEpF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,8BAA8B,GAAG,iBAAiB,GAAG;IAC/D,gBAAgB,EAAE,yBAAyB,EAAE,CAAC;CAC/C,CAAC;AAEF,KAAK,gBAAgB,GAAG,WAAW,CAAC,UAAU,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClF,KAAK,iBAAiB,GAAG,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;AAEzD,qBAAa,sBAAsB;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,kBAAkB;IAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,uBAAuB,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,8BAA8B,EAAE,CAAC;CA4B7C"}