node-autotask 0.31.0 → 0.33.0

package/dist/{index-Uqj987EE.d.ts → index-BaeMHZPk.d.ts}

@@ -1388,7 +1388,7 @@ declare class HttpClient {
  *   queryBounded noteChars free-text cap (issue #61 — response-side only);
  * - docs/API.md §11.7/§11.8/§11.9/§11.10/§11.11/§11.12 render the same facts.
  *
- * planHash: 030cd1af51b9263090d81a46ee44c1180d67e748d7b25383af89307684ff6b3c
+ * planHash: 913f1120488735c2e607cda13f9d551b11b3e6534d8a4b8310857d0bbd2fdb45
  */
 
 /** One pinned blind-surface stamp (the result-time sentinel object). */
@@ -2713,7 +2713,7 @@ interface CompaniesUpsertByNameResult {
     /** False when the dedup match short-circuited the create. */
     created: boolean;
     /** The matched record (present when created is false). */
-    existing?: Record<string, unknown>;
+    existing?: Company;
     /** The dedup boundary carried IN the result (a query-miss is NOT proof of absence). */
     blindSurface: CompaniesBlindSurfaceCaveat;
     /** The vendor side effects reported on the created result (the V5 auto-location). */
@@ -2824,6 +2824,90 @@ interface CompanyFullProfile {
     };
 }
 
+type CrmIntent = 'create_company' | 'add_contact' | 'update_contact' | 'update_company';
+interface CrmPrepareInput {
+    intent: CrmIntent;
+    company?: {
+        id?: number;
+        companyName?: string;
+        /** A bare domain or URL; derived from `website` or the contact email when omitted. */
+        domain?: string;
+        website?: string;
+        phone?: string;
+        companyType?: number;
+        ownerResourceID?: number;
+        address1?: string;
+        city?: string;
+        state?: string;
+        postalCode?: string;
+        countryID?: number;
+    };
+    contact?: {
+        id?: number;
+        firstName?: string;
+        lastName?: string;
+        emailAddress?: string;
+        phone?: string;
+        mobilePhone?: string;
+        companyLocationID?: number;
+        /** Used only to pick a location when the company has several. */
+        city?: string;
+        state?: string;
+        postalCode?: string;
+    };
+}
+/** One thing the caller must still supply, with how to get it. */
+interface CrmNeedsInput {
+    field: string;
+    why: string;
+    /** `live-proven`: the vendor demanded it on a real create; `policy`: this planner requires it (CRM hygiene). */
+    source: 'live-proven' | 'policy';
+    /** How to obtain the value: a lookup to run, or candidates to choose from. */
+    lookup?: Record<string, unknown>;
+    /** `web_if_available_else_ask`: search the web when the client can, otherwise ask the user; confirm any web-sourced value before writing. `lookup`: resolve it with the lookup, do not ask. `ask`: only the user knows. */
+    research: 'web_if_available_else_ask' | 'lookup' | 'ask';
+}
+interface CrmCompanyCandidate {
+    id: number;
+    companyName: string | null;
+    webAddress: string | null;
+    phone: string | null;
+    isActive: boolean | null;
+}
+interface CrmPrepareResult {
+    intent: CrmIntent;
+    company: {
+        status: 'matched' | 'ambiguous' | 'none' | 'not_searched';
+        matchedBy: string | null;
+        candidates: CrmCompanyCandidate[];
+    };
+    locations: null | {
+        items: Array<{
+            id: number;
+            name: string | null;
+            isPrimary: boolean | null;
+            isActive: boolean | null;
+            city: string | null;
+            state: string | null;
+            postalCode: string | null;
+        }>;
+        pick: {
+            rule: 'single' | 'matched' | 'ask' | 'none';
+            locationID: number | null;
+        };
+    };
+    contacts: null | {
+        duplicates: Array<Record<string, unknown>>;
+        matchedBy: 'email' | 'name' | null;
+    };
+    needsInput: CrmNeedsInput[];
+    next: null | {
+        operation: string;
+        note: string;
+    };
+    caveats: string[];
+}
+
 /** The closed `source` set for `companies.unbilledWork`. */
 type UnbilledWorkSource = 'posted_uninvoiced' | 'invoice' | 'date_range' | 'tickets';
 /** Options for `unbilledWork` (closed bag; the pinned defaults). */
@@ -3003,6 +3087,8 @@ declare class CompaniesResource extends BaseResource<Company, CompanyCreate, Com
     fullProfile(id: Identifier, opts?: CompanyFullProfileOptions): Promise<CompanyFullProfile>;
     /** Node-parity special op (hand-written in src/resources/special/companies.ts). */
     unbilledWork(id: Identifier, opts?: UnbilledWorkOptions): Promise<UnbilledWorkResult>;
+    /** Node-parity special op (hand-written in src/resources/special/companies.ts). */
+    prepareCrmWrite(input: CrmPrepareInput): Promise<CrmPrepareResult>;
 }
 
 /**
@@ -8039,15 +8125,44 @@ interface MoveManualAction {
     uiLink: string | null;
     reason: string;
 }
+/** The source record as read before the move (a vendor TimeEntry / TicketCharge row; fields vary by resource, so only the common ones are named). */
+interface MoveSnapshot {
+    id?: number;
+    ticketID?: number | null;
+    taskID?: number | null;
+    contractID?: number | null;
+    resourceID?: number;
+    lastModifiedDateTime?: string;
+    lastModifiedDate?: string;
+    /** Any other vendor field of the source record. */
+    [field: string]: unknown;
+}
+/** The soft facts a move reports (not refusals). */
+interface MoveFacts {
+    /** The tenant's closed-ticket-status read (or the disclosed fallback). */
+    closedStatus: {
+        closedIds: number[];
+        source: 'picklist' | 'assumed';
+        note: string;
+    };
+    sourceTicketId: number;
+    sourceCompanyID: number | null;
+    targetCompanyID: number | null;
+    /** null when the source ticket could not be read. */
+    companyChanged: boolean | null;
+    contractChanged: boolean | null;
+    /** Resource-specific soft facts added by a move spec's checkSource. */
+    [fact: string]: unknown;
+}
 interface MoveResult {
     status: MoveStatus;
     sourceId: number;
     newId: number;
     correlationId: string;
     /** The full source record as read before the delete — the caller persists it (the SDK stores nothing). */
-    snapshot: Record<string, unknown>;
+    snapshot: MoveSnapshot;
     /** Soft facts (not refusals): companyChanged, contractChanged, ... */
-    facts: Record<string, unknown>;
+    facts: MoveFacts;
     manualAction?: MoveManualAction;
 }
 interface MoveToTicketOptions {
@@ -8876,14 +8991,36 @@ declare class TicketWebhooksResource extends BaseResource<TicketWebhook, TicketW
  * behaviour bit-for-bit) under its historical name. */
 type TimeEntriesWindowOptions = DateWindowOptions;
 interface TimeEntriesStatusOptions {
-    /** Max records (default 500 = the hard cap, issue #128). */
+    /** Max entries read (default 500 = the hard cap, issue #128); `hasMore` flags a capped read. */
     limit?: number;
     /** Optional ticketID eq narrowing (node parity). */
     ticketID?: number;
+    /** Inclusive `dateWorked` window start, 'YYYY-MM-DD' (a calendar day, no tz shift — dateWorked is date-only). */
+    /** OPTIONAL, but pass it: a call without dates reads the tenant's first 500 time entries (effectively the oldest), a near-empty/misleading slice with `hasMore` true. */
+    dateFrom?: string;
+    /** Inclusive `dateWorked` window end, 'YYYY-MM-DD'. */
+    /** OPTIONAL, but pass it together with `dateFrom` (see there). */
+    dateTo?: string;
+}
+/** The getPosted / getUnposted result: the classified entries plus an honest truncation flag. */
+interface TimeEntriesPostedStateResult {
+    /** getPosted: entries a billing item references. getUnposted: entries no billing item references. */
+    items: TimeEntry[];
+    /** True when the entry read or a billing-item join page had more rows than one bounded page: the result is partial (a window with more than 500 entries returns the first 500) — narrow the window. */
+    hasMore: boolean;
+    /** The inclusive dateWorked window queried (second-precision UTC); a side is null when that bound was not given. */
+    window: {
+        from: string | null;
+        to: string | null;
+    };
+    /** INFORMATIONAL only, not posted state: items whose `billingApprovalDateTime` is set. Some tenants (ww29) never populate it. */
+    approvedCount: number;
+    /** INFORMATIONAL only, not posted state: items without `billingApprovalDateTime`. */
+    unapprovedCount: number;
 }
 /** postedWithin options: the optional narrowing + the shared limit bound. */
 interface TimeEntriesPostedWindowOptions {
-    /** Posted narrowing: `true` = posted rows only (postedDate exist), `false` = unposted rows only (postedDate notExist), omitted = both (the counts split the returned items). On a zone whose entity lacks the field (W-D3, e.g. ww29 — see the pointer note) the vendor 500s and the typed note explains. */
+    /** Posted narrowing, applied CLIENT-side after the billing-item join: `true` = posted rows only, `false` = unposted rows only (entries no billing item references), omitted = both. No postedDate condition is ever sent. */
     posted?: boolean;
     /** Max records (default 500 = the hard cap — a window with more than 500 matching rows: the bounded query op (time_entries.query) with the same dateWorked filter, its 2500-row walk cap; issue #128). */
     limit?: number;
@@ -8896,18 +9033,18 @@ interface TimeEntriesPostedWindowOptions {
 }
 /** The posted-window read result (issue #10): the window's items + the two-direction count in one pass. */
 interface TimeEntriesPostedWindowResult {
-    /** The window's entries (bounded by `limit`). */
+    /** The window's entries read, narrowed by `posted` when set (bounded by `limit`). */
     items: TimeEntry[];
-    /** The items carrying a set `postedDate` (the live-entity field — W-D3). */
+    /** Of EVERY entry read (before the `posted` narrowing), those a billing item references (the join — never a `postedDate` read). With `posted` set, `items.length` can differ from postedCount + unpostedCount. */
     postedCount: number;
-    /** The items with an empty `postedDate`. */
+    /** Of EVERY entry read (before the `posted` narrowing), those no billing item references — non-zero even with `posted: true` (entries whose join page was truncated are in neither count). */
     unpostedCount: number;
     /** The inclusive UTC window actually queried (wire bounds, second precision). */
     window: {
         from: string;
         to: string;
     };
-    /** True when the vendor reports more matching records than the bounded read returned (a live `pageDetails.nextPageUrl` cursor) — the posted/unposted counts then cover the returned rows ONLY (at most `limit`); re-query with a wider window or a narrowing filter to reconcile the totals. */
+    /** True when the entry read has a live `pageDetails.nextPageUrl` cursor (more matching records than the bounded read returned) OR a billing-item join page was truncated (those entries are in neither count) — the posted/unposted counts then cover the returned rows ONLY (at most `limit`); re-query with a wider window or a narrowing filter to reconcile the totals. */
     truncated: boolean;
 }
 
@@ -9115,9 +9252,9 @@ declare class TimeEntriesResource extends BaseResource<TimeEntry, TimeEntryCreat
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
     dateWorkedWindow(from: string, to: string, opts?: TimeEntriesPostedWindowOptions): Promise<TimeEntriesPostedWindowResult>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
-    getPosted(opts?: TimeEntriesStatusOptions): Promise<TimeEntry[]>;
+    getPosted(opts?: TimeEntriesStatusOptions): Promise<TimeEntriesPostedStateResult>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
-    getUnposted(opts?: TimeEntriesStatusOptions): Promise<TimeEntry[]>;
+    getUnposted(opts?: TimeEntriesStatusOptions): Promise<TimeEntriesPostedStateResult>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
     last14(opts?: TimeEntriesWindowOptions): Promise<TimeEntry[]>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */

package/dist/{index--5jrRl4u.d.cts → index-Cq0VsfSz.d.cts}

@@ -1388,7 +1388,7 @@ declare class HttpClient {
  *   queryBounded noteChars free-text cap (issue #61 — response-side only);
  * - docs/API.md §11.7/§11.8/§11.9/§11.10/§11.11/§11.12 render the same facts.
  *
- * planHash: 030cd1af51b9263090d81a46ee44c1180d67e748d7b25383af89307684ff6b3c
+ * planHash: 913f1120488735c2e607cda13f9d551b11b3e6534d8a4b8310857d0bbd2fdb45
  */
 
 /** One pinned blind-surface stamp (the result-time sentinel object). */
@@ -2713,7 +2713,7 @@ interface CompaniesUpsertByNameResult {
     /** False when the dedup match short-circuited the create. */
     created: boolean;
     /** The matched record (present when created is false). */
-    existing?: Record<string, unknown>;
+    existing?: Company;
     /** The dedup boundary carried IN the result (a query-miss is NOT proof of absence). */
     blindSurface: CompaniesBlindSurfaceCaveat;
     /** The vendor side effects reported on the created result (the V5 auto-location). */
@@ -2824,6 +2824,90 @@ interface CompanyFullProfile {
     };
 }
 
+type CrmIntent = 'create_company' | 'add_contact' | 'update_contact' | 'update_company';
+interface CrmPrepareInput {
+    intent: CrmIntent;
+    company?: {
+        id?: number;
+        companyName?: string;
+        /** A bare domain or URL; derived from `website` or the contact email when omitted. */
+        domain?: string;
+        website?: string;
+        phone?: string;
+        companyType?: number;
+        ownerResourceID?: number;
+        address1?: string;
+        city?: string;
+        state?: string;
+        postalCode?: string;
+        countryID?: number;
+    };
+    contact?: {
+        id?: number;
+        firstName?: string;
+        lastName?: string;
+        emailAddress?: string;
+        phone?: string;
+        mobilePhone?: string;
+        companyLocationID?: number;
+        /** Used only to pick a location when the company has several. */
+        city?: string;
+        state?: string;
+        postalCode?: string;
+    };
+}
+/** One thing the caller must still supply, with how to get it. */
+interface CrmNeedsInput {
+    field: string;
+    why: string;
+    /** `live-proven`: the vendor demanded it on a real create; `policy`: this planner requires it (CRM hygiene). */
+    source: 'live-proven' | 'policy';
+    /** How to obtain the value: a lookup to run, or candidates to choose from. */
+    lookup?: Record<string, unknown>;
+    /** `web_if_available_else_ask`: search the web when the client can, otherwise ask the user; confirm any web-sourced value before writing. `lookup`: resolve it with the lookup, do not ask. `ask`: only the user knows. */
+    research: 'web_if_available_else_ask' | 'lookup' | 'ask';
+}
+interface CrmCompanyCandidate {
+    id: number;
+    companyName: string | null;
+    webAddress: string | null;
+    phone: string | null;
+    isActive: boolean | null;
+}
+interface CrmPrepareResult {
+    intent: CrmIntent;
+    company: {
+        status: 'matched' | 'ambiguous' | 'none' | 'not_searched';
+        matchedBy: string | null;
+        candidates: CrmCompanyCandidate[];
+    };
+    locations: null | {
+        items: Array<{
+            id: number;
+            name: string | null;
+            isPrimary: boolean | null;
+            isActive: boolean | null;
+            city: string | null;
+            state: string | null;
+            postalCode: string | null;
+        }>;
+        pick: {
+            rule: 'single' | 'matched' | 'ask' | 'none';
+            locationID: number | null;
+        };
+    };
+    contacts: null | {
+        duplicates: Array<Record<string, unknown>>;
+        matchedBy: 'email' | 'name' | null;
+    };
+    needsInput: CrmNeedsInput[];
+    next: null | {
+        operation: string;
+        note: string;
+    };
+    caveats: string[];
+}
+
 /** The closed `source` set for `companies.unbilledWork`. */
 type UnbilledWorkSource = 'posted_uninvoiced' | 'invoice' | 'date_range' | 'tickets';
 /** Options for `unbilledWork` (closed bag; the pinned defaults). */
@@ -3003,6 +3087,8 @@ declare class CompaniesResource extends BaseResource<Company, CompanyCreate, Com
     fullProfile(id: Identifier, opts?: CompanyFullProfileOptions): Promise<CompanyFullProfile>;
     /** Node-parity special op (hand-written in src/resources/special/companies.ts). */
     unbilledWork(id: Identifier, opts?: UnbilledWorkOptions): Promise<UnbilledWorkResult>;
+    /** Node-parity special op (hand-written in src/resources/special/companies.ts). */
+    prepareCrmWrite(input: CrmPrepareInput): Promise<CrmPrepareResult>;
 }
 
 /**
@@ -8039,15 +8125,44 @@ interface MoveManualAction {
     uiLink: string | null;
     reason: string;
 }
+/** The source record as read before the move (a vendor TimeEntry / TicketCharge row; fields vary by resource, so only the common ones are named). */
+interface MoveSnapshot {
+    id?: number;
+    ticketID?: number | null;
+    taskID?: number | null;
+    contractID?: number | null;
+    resourceID?: number;
+    lastModifiedDateTime?: string;
+    lastModifiedDate?: string;
+    /** Any other vendor field of the source record. */
+    [field: string]: unknown;
+}
+/** The soft facts a move reports (not refusals). */
+interface MoveFacts {
+    /** The tenant's closed-ticket-status read (or the disclosed fallback). */
+    closedStatus: {
+        closedIds: number[];
+        source: 'picklist' | 'assumed';
+        note: string;
+    };
+    sourceTicketId: number;
+    sourceCompanyID: number | null;
+    targetCompanyID: number | null;
+    /** null when the source ticket could not be read. */
+    companyChanged: boolean | null;
+    contractChanged: boolean | null;
+    /** Resource-specific soft facts added by a move spec's checkSource. */
+    [fact: string]: unknown;
+}
 interface MoveResult {
     status: MoveStatus;
     sourceId: number;
     newId: number;
     correlationId: string;
     /** The full source record as read before the delete — the caller persists it (the SDK stores nothing). */
-    snapshot: Record<string, unknown>;
+    snapshot: MoveSnapshot;
     /** Soft facts (not refusals): companyChanged, contractChanged, ... */
-    facts: Record<string, unknown>;
+    facts: MoveFacts;
     manualAction?: MoveManualAction;
 }
 interface MoveToTicketOptions {
@@ -8876,14 +8991,36 @@ declare class TicketWebhooksResource extends BaseResource<TicketWebhook, TicketW
  * behaviour bit-for-bit) under its historical name. */
 type TimeEntriesWindowOptions = DateWindowOptions;
 interface TimeEntriesStatusOptions {
-    /** Max records (default 500 = the hard cap, issue #128). */
+    /** Max entries read (default 500 = the hard cap, issue #128); `hasMore` flags a capped read. */
     limit?: number;
     /** Optional ticketID eq narrowing (node parity). */
     ticketID?: number;
+    /** Inclusive `dateWorked` window start, 'YYYY-MM-DD' (a calendar day, no tz shift — dateWorked is date-only). */
+    /** OPTIONAL, but pass it: a call without dates reads the tenant's first 500 time entries (effectively the oldest), a near-empty/misleading slice with `hasMore` true. */
+    dateFrom?: string;
+    /** Inclusive `dateWorked` window end, 'YYYY-MM-DD'. */
+    /** OPTIONAL, but pass it together with `dateFrom` (see there). */
+    dateTo?: string;
+}
+/** The getPosted / getUnposted result: the classified entries plus an honest truncation flag. */
+interface TimeEntriesPostedStateResult {
+    /** getPosted: entries a billing item references. getUnposted: entries no billing item references. */
+    items: TimeEntry[];
+    /** True when the entry read or a billing-item join page had more rows than one bounded page: the result is partial (a window with more than 500 entries returns the first 500) — narrow the window. */
+    hasMore: boolean;
+    /** The inclusive dateWorked window queried (second-precision UTC); a side is null when that bound was not given. */
+    window: {
+        from: string | null;
+        to: string | null;
+    };
+    /** INFORMATIONAL only, not posted state: items whose `billingApprovalDateTime` is set. Some tenants (ww29) never populate it. */
+    approvedCount: number;
+    /** INFORMATIONAL only, not posted state: items without `billingApprovalDateTime`. */
+    unapprovedCount: number;
 }
 /** postedWithin options: the optional narrowing + the shared limit bound. */
 interface TimeEntriesPostedWindowOptions {
-    /** Posted narrowing: `true` = posted rows only (postedDate exist), `false` = unposted rows only (postedDate notExist), omitted = both (the counts split the returned items). On a zone whose entity lacks the field (W-D3, e.g. ww29 — see the pointer note) the vendor 500s and the typed note explains. */
+    /** Posted narrowing, applied CLIENT-side after the billing-item join: `true` = posted rows only, `false` = unposted rows only (entries no billing item references), omitted = both. No postedDate condition is ever sent. */
     posted?: boolean;
     /** Max records (default 500 = the hard cap — a window with more than 500 matching rows: the bounded query op (time_entries.query) with the same dateWorked filter, its 2500-row walk cap; issue #128). */
     limit?: number;
@@ -8896,18 +9033,18 @@ interface TimeEntriesPostedWindowOptions {
 }
 /** The posted-window read result (issue #10): the window's items + the two-direction count in one pass. */
 interface TimeEntriesPostedWindowResult {
-    /** The window's entries (bounded by `limit`). */
+    /** The window's entries read, narrowed by `posted` when set (bounded by `limit`). */
     items: TimeEntry[];
-    /** The items carrying a set `postedDate` (the live-entity field — W-D3). */
+    /** Of EVERY entry read (before the `posted` narrowing), those a billing item references (the join — never a `postedDate` read). With `posted` set, `items.length` can differ from postedCount + unpostedCount. */
     postedCount: number;
-    /** The items with an empty `postedDate`. */
+    /** Of EVERY entry read (before the `posted` narrowing), those no billing item references — non-zero even with `posted: true` (entries whose join page was truncated are in neither count). */
     unpostedCount: number;
     /** The inclusive UTC window actually queried (wire bounds, second precision). */
     window: {
         from: string;
         to: string;
     };
-    /** True when the vendor reports more matching records than the bounded read returned (a live `pageDetails.nextPageUrl` cursor) — the posted/unposted counts then cover the returned rows ONLY (at most `limit`); re-query with a wider window or a narrowing filter to reconcile the totals. */
+    /** True when the entry read has a live `pageDetails.nextPageUrl` cursor (more matching records than the bounded read returned) OR a billing-item join page was truncated (those entries are in neither count) — the posted/unposted counts then cover the returned rows ONLY (at most `limit`); re-query with a wider window or a narrowing filter to reconcile the totals. */
     truncated: boolean;
 }
 
@@ -9115,9 +9252,9 @@ declare class TimeEntriesResource extends BaseResource<TimeEntry, TimeEntryCreat
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
     dateWorkedWindow(from: string, to: string, opts?: TimeEntriesPostedWindowOptions): Promise<TimeEntriesPostedWindowResult>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
-    getPosted(opts?: TimeEntriesStatusOptions): Promise<TimeEntry[]>;
+    getPosted(opts?: TimeEntriesStatusOptions): Promise<TimeEntriesPostedStateResult>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
-    getUnposted(opts?: TimeEntriesStatusOptions): Promise<TimeEntry[]>;
+    getUnposted(opts?: TimeEntriesStatusOptions): Promise<TimeEntriesPostedStateResult>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */
     last14(opts?: TimeEntriesWindowOptions): Promise<TimeEntry[]>;
     /** Node-parity special op (hand-written in src/resources/special/time_entries.ts). */