@macro-inc/sdk 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (138) hide show
  1. package/README.md +156 -23
  2. package/dist/{chunk-3SW6QVDV.js → chunk-4MI52GWV.js} +60 -1
  3. package/dist/{chunk-GT5EUYOR.js → chunk-HO75UE4Z.js} +133 -0
  4. package/dist/{chunk-P4DTO6VD.js → chunk-MCSQNZ4E.js} +6 -0
  5. package/dist/{chunk-HIW6KU2I.js → chunk-SJ6S2GAT.js} +712 -14
  6. package/dist/{chunk-J2VK3NOR.js → chunk-SK5CMXRV.js} +44 -14
  7. package/dist/{chunk-UVJLWLSJ.js → chunk-TMTYN2UK.js} +190 -2
  8. package/dist/{chunk-PPR7IWZ7.js → chunk-ZYBAKW25.js} +2 -1
  9. package/dist/generated/agent-fold/index.d.ts +194 -8
  10. package/dist/generated/agent-harness/index.d.ts +1 -1
  11. package/dist/generated/agent-harness/index.js +1 -1
  12. package/dist/generated/agent-harness/sdk.gen.d.ts +33 -2
  13. package/dist/generated/agent-harness/types.gen.d.ts +341 -8
  14. package/dist/generated/agent-reviews/index.d.ts +11 -9
  15. package/dist/generated/auth/index.d.ts +1 -1
  16. package/dist/generated/auth/index.js +1 -1
  17. package/dist/generated/auth/sdk.gen.d.ts +69 -1
  18. package/dist/generated/auth/types.gen.d.ts +734 -3
  19. package/dist/generated/calendar/types.gen.d.ts +10 -3
  20. package/dist/generated/cognition/index.d.ts +1 -1
  21. package/dist/generated/cognition/index.js +1 -1
  22. package/dist/generated/cognition/sdk.gen.d.ts +23 -6
  23. package/dist/generated/cognition/types.gen.d.ts +202 -114
  24. package/dist/generated/contacts/index.d.ts +1 -1
  25. package/dist/generated/contacts/index.js +1 -1
  26. package/dist/generated/contacts/sdk.gen.d.ts +5 -1
  27. package/dist/generated/contacts/types.gen.d.ts +56 -0
  28. package/dist/generated/email/types.gen.d.ts +8 -2
  29. package/dist/generated/notification/index.d.ts +1 -1
  30. package/dist/generated/notification/index.js +1 -1
  31. package/dist/generated/notification/sdk.gen.d.ts +2 -1
  32. package/dist/generated/notification/types.gen.d.ts +138 -0
  33. package/dist/generated/scheduled-action/index.d.ts +1 -1
  34. package/dist/generated/scheduled-action/index.js +1 -1
  35. package/dist/generated/scheduled-action/sdk.gen.d.ts +92 -2
  36. package/dist/generated/scheduled-action/types.gen.d.ts +1455 -21
  37. package/dist/generated/search/index.d.ts +1 -1
  38. package/dist/generated/search/types.gen.d.ts +50 -11
  39. package/dist/generated/storage/index.d.ts +1 -1
  40. package/dist/generated/storage/index.js +1 -1
  41. package/dist/generated/storage/sdk.gen.d.ts +309 -15
  42. package/dist/generated/storage/types.gen.d.ts +12437 -8899
  43. package/dist/src/entities/agent-sessions/activity.d.ts +3 -2
  44. package/dist/src/entities/agent-sessions/agent-session.d.ts +17 -5
  45. package/dist/src/entities/agent-sessions/namespace.d.ts +5 -4
  46. package/dist/src/entities/agent-sessions/review.d.ts +1 -1
  47. package/dist/src/entities/ai/namespace.d.ts +2 -2
  48. package/dist/src/entities/api-keys/namespace.d.ts +5 -2
  49. package/dist/src/entities/bots/bot.d.ts +6 -3
  50. package/dist/src/entities/calendar/booking-namespace.d.ts +1 -1
  51. package/dist/src/entities/calendar/calendar.d.ts +3 -2
  52. package/dist/src/entities/calendar/event.d.ts +9 -0
  53. package/dist/src/entities/calendar/namespace.d.ts +3 -2
  54. package/dist/src/entities/calls/call-record.d.ts +19 -5
  55. package/dist/src/entities/canvases/canvas.d.ts +5 -0
  56. package/dist/src/entities/channels/channel.d.ts +27 -7
  57. package/dist/src/entities/channels/message.d.ts +65 -2
  58. package/dist/src/entities/channels/message.test.d.ts +1 -0
  59. package/dist/src/entities/channels/namespace.d.ts +9 -4
  60. package/dist/src/entities/channels/post.d.ts +13 -7
  61. package/dist/src/entities/channels/share.d.ts +9 -0
  62. package/dist/src/entities/channels/share.test.d.ts +1 -0
  63. package/dist/src/entities/channels/thread.d.ts +5 -1
  64. package/dist/src/entities/chats/chat.d.ts +1 -1
  65. package/dist/src/entities/chats/namespace.d.ts +1 -1
  66. package/dist/src/entities/connected-apps/connected-app.d.ts +2 -1
  67. package/dist/src/entities/connected-apps/namespace.d.ts +2 -0
  68. package/dist/src/entities/crm/company.d.ts +1 -1
  69. package/dist/src/entities/crm/contact.d.ts +44 -3
  70. package/dist/src/entities/crm/namespace.d.ts +30 -13
  71. package/dist/src/entities/crm/pipeline-entry.d.ts +10 -3
  72. package/dist/src/entities/crm/pipeline.d.ts +39 -20
  73. package/dist/src/entities/crm/pipelines.d.ts +33 -5
  74. package/dist/src/entities/crm-email-privacy/email-privacy.d.ts +238 -0
  75. package/dist/src/entities/crm-email-privacy/email-rule-preview.d.ts +55 -0
  76. package/dist/src/entities/crm-email-privacy/email-rule-revision.d.ts +27 -0
  77. package/dist/src/entities/crm-email-privacy/email-rules.d.ts +32 -0
  78. package/dist/src/entities/databases/database.d.ts +34 -6
  79. package/dist/src/entities/databases/namespace.d.ts +26 -6
  80. package/dist/src/entities/databases/saved-query.d.ts +7 -1
  81. package/dist/src/entities/databases/table.d.ts +9 -0
  82. package/dist/src/entities/databases/view.d.ts +10 -0
  83. package/dist/src/entities/documents/create.test.d.ts +1 -0
  84. package/dist/src/entities/documents/document.d.ts +41 -6
  85. package/dist/src/entities/documents/namespace.d.ts +17 -3
  86. package/dist/src/entities/email/draft.d.ts +2 -2
  87. package/dist/src/entities/email/message.d.ts +18 -7
  88. package/dist/src/entities/email/namespace.d.ts +11 -7
  89. package/dist/src/entities/email/thread.d.ts +26 -3
  90. package/dist/src/entities/entity.d.ts +10 -1
  91. package/dist/src/entities/external-chat/chat.d.ts +19 -2
  92. package/dist/src/entities/foreign/namespace.d.ts +1 -1
  93. package/dist/src/entities/forms/form.d.ts +20 -1
  94. package/dist/src/entities/harnesses/namespace.d.ts +1 -1
  95. package/dist/src/entities/harnesses/pairing.d.ts +2 -1
  96. package/dist/src/entities/imports/entry.d.ts +65 -0
  97. package/dist/src/entities/imports/namespace.d.ts +103 -0
  98. package/dist/src/entities/imports/namespace.test.d.ts +1 -0
  99. package/dist/src/entities/initiatives/initiative.d.ts +14 -4
  100. package/dist/src/entities/initiatives/namespace.d.ts +4 -2
  101. package/dist/src/entities/me/namespace.d.ts +1 -1
  102. package/dist/src/entities/meetings/meeting.d.ts +2 -1
  103. package/dist/src/entities/notifications/namespace.d.ts +2 -1
  104. package/dist/src/entities/notifications/notification.d.ts +2 -1
  105. package/dist/src/entities/passwords/item.d.ts +118 -0
  106. package/dist/src/entities/passwords/namespace.d.ts +45 -0
  107. package/dist/src/entities/projects/namespace.d.ts +1 -1
  108. package/dist/src/entities/projects/project.d.ts +11 -1
  109. package/dist/src/entities/referrals/namespace.d.ts +1 -1
  110. package/dist/src/entities/routines/namespace.d.ts +81 -18
  111. package/dist/src/entities/routines/routine.d.ts +65 -4
  112. package/dist/src/entities/routines/suggestion.d.ts +38 -0
  113. package/dist/src/entities/saved-views/namespace.d.ts +2 -1
  114. package/dist/src/entities/search/exclusions.d.ts +6 -0
  115. package/dist/src/entities/search/namespace.d.ts +4 -2
  116. package/dist/src/entities/search/options.d.ts +3 -2
  117. package/dist/src/entities/suggestions/namespace.d.ts +118 -0
  118. package/dist/src/entities/suggestions/suggestion.d.ts +172 -0
  119. package/dist/src/entities/suggestions/suggestion.test.d.ts +1 -0
  120. package/dist/src/entities/tasks/namespace.d.ts +6 -5
  121. package/dist/src/entities/tasks/task.d.ts +14 -2
  122. package/dist/src/entities/teams/team.d.ts +16 -3
  123. package/dist/src/entities/ui/app-link.d.ts +24 -0
  124. package/dist/src/entities/ui/namespace.d.ts +75 -0
  125. package/dist/src/entities/users/namespace.d.ts +7 -3
  126. package/dist/src/entities/web/namespace.d.ts +2 -2
  127. package/dist/src/entities/workspace/namespace.d.ts +5 -3
  128. package/dist/src/entities/workspace/query.test.d.ts +1 -0
  129. package/dist/src/events/hydrate/document.d.ts +5 -0
  130. package/dist/src/macro.d.ts +26 -1
  131. package/dist/src/macro.js +4086 -1234
  132. package/dist/src/utils/activity.d.ts +2 -0
  133. package/dist/src/utils/index.d.ts +1 -1
  134. package/dist/src/utils/lazy.d.ts +13 -0
  135. package/dist/src/utils/options.d.ts +7 -0
  136. package/dist/src/utils/pagination.d.ts +16 -0
  137. package/dist/src/utils/verbs.d.ts +3 -0
  138. package/package.json +1 -1
@@ -109,7 +109,7 @@ export declare class Chat extends PropertiedEntity<ChatDetail> implements Mentio
109
109
  id: string;
110
110
  detail?: import("../../../generated/cognition").ChatResponse | undefined;
111
111
  };
112
- /** Search chats by name and content, most relevant first, auto-paginated. */
112
+ /** Search chats by name and content, most relevant first, auto-paginated; `maxItems` caps the total. */
113
113
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Chat, any, any>;
114
114
  /**
115
115
  * Render this chat as a mention for a message body.
@@ -27,7 +27,7 @@ export declare class ChatNamespace {
27
27
  project?: Project;
28
28
  }): Promise<Chat>;
29
29
  /**
30
- * Search AI chats by name and content, most relevant first, auto-paginated.
30
+ * Search AI chats by name and content, most relevant first, auto-paginated; `maxItems` caps the total.
31
31
  *
32
32
  * @readonly
33
33
  */
@@ -99,7 +99,8 @@ export declare class ConnectedTool {
99
99
  * unanswered call comes back with `isError`. Check `isError` on the result: an app that is not connected,
100
100
  * or whose connection expired, answers with `isError` and text telling you
101
101
  * what to say to the user, including any connect markup to put in your
102
- * reply verbatim.
102
+ * reply verbatim. Throws when the app is still rate limiting the account
103
+ * after Macro paced and retried the call; the call did not run.
103
104
  *
104
105
  * @destructive
105
106
  * @openworld
@@ -18,6 +18,8 @@ export type { ConnectMcpServerResponse };
18
18
  *
19
19
  * Calls run in the user's real account through Macro's server, as the account this execution acts as, and take effect at once; the program never sees a credential. In a turn someone other than the session's owner prompted, each call that uses the owner's account waits for the owner to approve it, so make few such calls and expect a long wait or a refusal. Read before writing, and never repeat a write whose outcome is unknown: check the app's state first. A result with `isError` explains itself: when it says an app is not connected, tell the user and include the connect markup it gives you in your reply verbatim, then stop.
20
20
  *
21
+ * Each account's calls to one app share a budget across its running programs on the same Macro server: a few run at once, paced, and the rest queue. Narrow first with the app's search or list tools and their own limits and filters (e.g. open PRs updated this week), then call per item only for the few items you need, in small batches; never `Promise.all` a call per item over a whole list. A call the app keeps refusing with HTTP 429 is retried after its `Retry-After`; one still refused throws a rate-limit error and did not run, so stop and report partial results rather than retrying in a loop.
22
+ *
21
23
  * When an app the work needs is missing, find it with `macro.connectedApps.discover(execution, appName)` and `connector.inspect()` its advertised actions and connection status. Recommend connecting only when an advertised action supports the task; an app's name is not evidence. For a suitable unconnected app, put the inspection's `connectMarkup` in your reply verbatim and say what connecting enables. To add a remote MCP server the user gives you the URL of, use `macro.connectedApps.addServer(execution, {url, serverName})`; never guess a URL, and tell the user to sign in under Settings → Connections when its summary says so.
22
24
  *
23
25
  * ```javascript
@@ -81,7 +81,7 @@ export declare class Company extends PropertiedEntity<CompanyDetail> {
81
81
  * @readonly
82
82
  */
83
83
  contacts(): Promise<Contact[]>;
84
- /** Search CRM companies by name/domain, most relevant first, auto-paginated. */
84
+ /** Search CRM companies by name/domain, most relevant first, auto-paginated; `maxItems` caps the total. */
85
85
  static search: (client: MacroClient, query: string, searchOpts?: import("../search/options").SearchOpts) => AsyncGenerator<Company, any, any>;
86
86
  /**
87
87
  * Hide the company from CRM listings: disables email sync and soft-hides
@@ -48,8 +48,20 @@ export declare class Contact extends FavoritableEntity<ContactDetail> {
48
48
  static from(client: MacroClient, data: ContactDetail): Contact;
49
49
  /** The contact's display name, if one has been observed. */
50
50
  readonly name: () => Promise<string | undefined>;
51
- /** The contact's email address; absent for a contact added by name alone. */
51
+ /** The contact's primary email address; absent for a contact added by name alone. */
52
52
  readonly email: () => Promise<string | undefined>;
53
+ /** Every address the contact is known by: the primary first, then the rest oldest first. */
54
+ readonly emails: () => Promise<string[]>;
55
+ /**
56
+ * Whether the contact has an address on one of its company's domains. Such a
57
+ * contact cannot be unlinked from the company or moved to another.
58
+ */
59
+ readonly companyDomain: () => Promise<NonNullable<boolean | undefined>>;
60
+ /**
61
+ * The addresses on one of the company's domains. The last one cannot be
62
+ * removed while the contact is linked to the company.
63
+ */
64
+ readonly companyDomainEmails: () => Promise<string[]>;
53
65
  /** The CRM company this contact belongs to, if it has one. */
54
66
  readonly company: () => Promise<Company | undefined>;
55
67
  /** Whether the contact is hidden from CRM listings. */
@@ -85,19 +97,48 @@ export declare class Contact extends FavoritableEntity<ContactDetail> {
85
97
  */
86
98
  rename(name: string): Promise<void>;
87
99
  /**
88
- * Add an email when absent. Existing addresses cannot be replaced or cleared.
100
+ * Make an address the contact's primary, adding it when the contact does not
101
+ * hold it yet. The previous primary stays on the contact.
89
102
  *
90
103
  * @write
91
104
  * @idempotent
92
105
  */
93
106
  setEmail(email: string): Promise<void>;
94
107
  /**
95
- * Link or switch a personal-provider contact's company. Unlinking is not supported.
108
+ * Add a further address the contact is known by. It must not belong to
109
+ * another contact in the team, and becomes the primary only when the contact
110
+ * has none.
111
+ *
112
+ * @write
113
+ * @idempotent
114
+ */
115
+ addEmail(email: string): Promise<void>;
116
+ /**
117
+ * Remove one of the contact's addresses. Nothing else is deleted: the contact
118
+ * stops showing that address's email history. Removing the primary promotes
119
+ * the oldest address left. The last address on a domain of the contact's
120
+ * company cannot be removed while the contact is linked to it.
121
+ *
122
+ * @destructive
123
+ * @idempotent
124
+ */
125
+ removeEmail(email: string): Promise<void>;
126
+ /**
127
+ * Link or switch the company of a contact whose primary address is on a
128
+ * personal provider. Rejected for a contact on its company's domain.
96
129
  *
97
130
  * @write
98
131
  * @idempotent
99
132
  */
100
133
  setCompany(company: Company): Promise<void>;
134
+ /**
135
+ * Remove the contact's company link, leaving a contact without a company.
136
+ * Rejected for a contact on its company's domain.
137
+ *
138
+ * @write
139
+ * @idempotent
140
+ */
141
+ unlinkCompany(): Promise<void>;
101
142
  /** The CRM record this contact's discussions hang off. */
102
143
  private get commentParent();
103
144
  /**
@@ -1,28 +1,43 @@
1
1
  import type { CreateCrmCompanyRequest, CreateCrmTeamContactRequest, CrmStagesResponse, CrmTeamSettingsResponse, PipelineSharing, ReplaceCrmStagesRequest, UpdateCrmTeamSettingsRequest } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
+ import { CrmEmailPrivacyNamespace } from '../crm-email-privacy/email-privacy';
3
4
  import type { Document } from '../documents/document';
5
+ import type { SearchOpts } from '../search/options';
6
+ import { Team } from '../teams/team';
4
7
  import { Company } from './company';
5
8
  import { Contact } from './contact';
6
9
  import { CrmPipeline } from './pipeline';
7
10
  import { type CompanyImport } from './pipeline-entry';
8
11
  import { PipelineNamespace } from './pipelines';
9
12
  /**
10
- * @routing Use when working with CRM deals, pipelines, stages, companies or contacts; not generic databases, and not a search that merely names a company.
13
+ * @routing Use when working with CRM records and pipelines; not generic databases or email contribution.
11
14
  *
12
15
  * @agent
13
16
  * ## How CRM pipelines work
14
17
  *
15
18
  * A pipeline is a board of deals. Each entry tracks one CRM company or contact and has its own fields: usually Stage, Owner and Revenue, plus any the team added. "Deal", "opportunity", "lead", "the pipeline", "move Acme to Negotiation" and "who's in Demo" all refer to pipeline entries. A pipeline is not a Macro database: work with it through the CRM pipeline methods, never database queries or SQL.
16
19
  *
17
- * Work with entries by name through the pipeline's own methods: `find` (filters by field name and stage label, with per-stage counts and number totals such as Revenue), `addRecords`, `updateEntries` (a stage by its label, a person as `'me'`), `removeRecords`, and `edit` for fields and stage options. `importCsv` / `exportCsv` move entries through CSV, and `crm.importCompaniesCsv` loads a companies list. `crm.pipelines.entriesFor` and `searchEntries` find a company's deals across pipelines. Reach for `applyOps` and column ids only for what these cannot express.
20
+ * Create a pipeline with its stages and fields in one `crm.pipelines.create` call. Work with entries by name through the pipeline's own methods: `find` (filters by field name and stage label, with per-stage counts and number totals such as Revenue), `addRecords`, `updateEntries` (a stage by its label, a person as `'me'`), `removeRecords`, and `edit` for fields and stage options. `importCsv` / `exportCsv` move entries through CSV, and `crm.importCompaniesCsv` loads a companies list. `crm.pipelines.entriesFor` and `searchEntries` find a company's deals across pipelines. Reach for `applyOps` and column ids only for what these cannot express.
18
21
  *
19
22
  * A company also has its own Stage, Owner and Revenue properties on its CRM page. They are separate from every pipeline and not kept in sync with it. When the user has pipelines, deal and stage requests mean pipeline entries; change the company's own properties only when the user asks for those properties specifically.
20
23
  */
21
24
  export declare class CrmNamespace {
22
25
  private readonly client;
26
+ /** Your email contribution. */
27
+ readonly emailPrivacy: CrmEmailPrivacyNamespace;
23
28
  /** Pipelines, their records and sharing settings. */
24
29
  readonly pipelines: PipelineNamespace;
25
30
  constructor(client: MacroClient);
31
+ /**
32
+ * Read the caller's current CRM access, including when access is denied.
33
+ * Existing handles do not bypass the server's current permission checks.
34
+ *
35
+ * @readonly
36
+ */
37
+ access(): Promise<{
38
+ team?: Team;
39
+ allowed: boolean;
40
+ }>;
26
41
  /**
27
42
  * A handle to a CRM company by id.
28
43
  *
@@ -74,21 +89,23 @@ export declare class CrmNamespace {
74
89
  */
75
90
  blockedDomains(): Promise<string[]>;
76
91
  /**
77
- * Block a domain (like `acme.com`): email sync skips it, and the company
78
- * that owns it, that company's contacts, and contacts without a company at
79
- * the domain are hidden. A contact attached to another company follows that
80
- * company's domains. Requires a team admin or owner.
92
+ * Block a domain from email sync without changing existing CRM records.
93
+ *
94
+ * Existing companies, contacts and their hidden states are preserved.
95
+ * Requires a team admin or owner.
81
96
  *
82
97
  * @destructive
83
98
  * @idempotent
99
+ * @throws When the domain equals or covers a member's connected primary
100
+ * mailbox domain. The error preserves the server's explanation.
84
101
  */
85
102
  blockDomain(domain: string): Promise<void>;
86
103
  /**
87
- * Unblock a domain: email sync resumes for addresses the team's
88
- * personal-email and generic-provider filters allow. Contacts without a
89
- * company at this domain are shown again. Its company and attached contacts
90
- * stay hidden until the company's last blocked domain is removed, then are
91
- * shown even if hidden by hand before blocking. Requires a team admin or owner.
104
+ * Resume eligible email sync for a domain without changing existing CRM records.
105
+ *
106
+ * Email sync resumes for addresses the team's personal-email and
107
+ * generic-provider filters allow. Existing companies, contacts and their
108
+ * hidden states are preserved. Requires a team admin or owner.
92
109
  *
93
110
  * @write
94
111
  * @idempotent
@@ -138,9 +155,9 @@ export declare class CrmNamespace {
138
155
  };
139
156
  }): Promise<CompanyImport>;
140
157
  /**
141
- * Search CRM companies by name/domain, most relevant first, auto-paginated.
158
+ * Search CRM companies by name/domain, most relevant first, auto-paginated; `maxItems` caps the total.
142
159
  *
143
160
  * @readonly
144
161
  */
145
- searchCompanies(query: string): AsyncGenerator<Company>;
162
+ searchCompanies(query: string, opts?: SearchOpts): AsyncGenerator<Company>;
146
163
  }
@@ -17,11 +17,16 @@ export type PipelineFieldInputs = Record<string, PipelineFieldInput>;
17
17
  export type PipelineFieldValue = EntryFieldValue;
18
18
  /** A field of a pipeline as entries and filters name it. */
19
19
  export type PipelineField = PipelineFieldSummary;
20
- /** A field's value before and after an update; `undefined` when empty. */
20
+ /**
21
+ * A field's value before and after an update; `undefined` when empty. A
22
+ * monetary field also carries the currency code of each amount.
23
+ */
21
24
  export type PipelineFieldChange = {
22
25
  field: string;
23
26
  before: PipelineFieldValue | undefined;
24
27
  after: PipelineFieldValue | undefined;
28
+ beforeCurrency?: string;
29
+ afterCurrency?: string;
25
30
  };
26
31
  /** The company or contact an entry tracks, or a contact's email to add (in a company pipeline, its company). */
27
32
  export type PipelineRecordInput = Company | Contact | {
@@ -48,8 +53,10 @@ export declare function fieldInputs(set: PipelineFieldInputs): FieldValueInput[]
48
53
  /** @internal A pipeline import with its pipeline as a handle. */
49
54
  export declare function pipelineImport(pipeline: CrmPipeline, outcome: PipelineImportResponse): PipelineImport;
50
55
  /**
51
- * One entry of a CRM pipeline (a deal): the company or contact it tracks
52
- * (none in a generic pipeline of free-form rows) and its fields by name. Change it with {@link PipelineEntry.update} or take it
56
+ * A CRM pipeline entry (a deal), with its fields by name.
57
+ *
58
+ * It tracks a company or contact, or neither in a generic pipeline of
59
+ * free-form rows. Change it with {@link PipelineEntry.update} or take it
53
60
  * out with {@link PipelineEntry.remove}.
54
61
  *
55
62
  * @mcp-exclude Built from a pipeline listing; use CrmPipeline.updateEntries and removeRecords.
@@ -1,4 +1,5 @@
1
1
  import type { AccessiblePipeline, CardPosition, ColumnDetail, CreatePipeline, DatabaseOp, DatabaseView as DatabaseViewRecord, EditPipelineRequest, StorageRow, StorageRowsQuery, TableDetail } from '../../../generated/storage/types.gen';
2
+ import { type IterationOptions } from '../../utils';
2
3
  import type { MacroClient } from '../../utils/client';
3
4
  import { Document } from '../documents/document';
4
5
  import { MacroEntity } from '../entity';
@@ -104,19 +105,20 @@ export declare class CrmPipeline extends MacroEntity<AccessiblePipeline> {
104
105
  */
105
106
  tableRecord(): Promise<TableDetail>;
106
107
  /**
107
- * Rows in pipeline order, automatically paginated.
108
+ * Rows in pipeline order, automatically paginated; `maxItems` caps the total.
108
109
  *
109
110
  * @readonly
110
111
  */
111
- rows(): AsyncGenerator<PipelineRow>;
112
+ rows(opts?: IterationOptions): AsyncGenerator<PipelineRow>;
112
113
  /**
113
- * Query pipeline rows, optionally restricting the query to typed row handles.
114
+ * Query pipeline rows, optionally restricting the query to typed row handles; `maxItems` caps the total.
114
115
  *
115
116
  * @readonly
116
117
  */
117
118
  queryRows(options?: {
118
119
  query?: StorageRowsQuery['query'];
119
120
  rows?: PipelineRow[];
121
+ maxItems?: number;
120
122
  }): AsyncGenerator<PipelineRow>;
121
123
  /**
122
124
  * Add companies or contacts as entries (deals), filling fields by name: a
@@ -172,11 +174,15 @@ export declare class CrmPipeline extends MacroEntity<AccessiblePipeline> {
172
174
  version: number | undefined;
173
175
  }>;
174
176
  /**
175
- * Read entries by field name and label: `where` filters (`{ Stage: 'Demo' }`,
176
- * a list for any of several, `null` for empty), only some companies or
177
- * contacts, or a search of their names, domains and emails; sorted by a
178
- * field. Also answers per-stage counts and number totals (such as Revenue)
179
- * over every match, and the pipeline's fields and version.
177
+ * Read entries by field name and label.
178
+ *
179
+ * `where` filters by field values (`{ Stage: 'Demo' }`, a list for any of
180
+ * several, `null` for empty). Restrict to some companies or contacts, or
181
+ * search their names, domains and emails; sort by a field.
182
+ * Also answers per-stage counts and number totals (such as Revenue)
183
+ * over every match, and the pipeline's fields and version. A monetary field
184
+ * (one whose field summary names a `currencyField`) has one total per
185
+ * `currency`; amounts in different currencies are never converted or added.
180
186
  *
181
187
  * @param query.limit Most entries to return, 1 to 5000 (default 50); counts and totals cover every match.
182
188
  *
@@ -199,9 +205,11 @@ export declare class CrmPipeline extends MacroEntity<AccessiblePipeline> {
199
205
  version: number;
200
206
  }>;
201
207
  /**
202
- * Rename or share the pipeline and change its fields and options by name,
203
- * in one change: add fields (text, number, checkbox, date, link, select,
204
- * multi_select, person or people), rename or delete fields, and add,
208
+ * Edit pipeline sharing, fields and options together.
209
+ *
210
+ * Rename or share the pipeline; change fields and options by name: add
211
+ * fields (text, number, checkbox, date, link, select, multi_select, person or
212
+ * people), rename or delete fields, and add,
205
213
  * relabel or delete options (new Stage options become the last stages).
206
214
  * Returns the fields and version afterwards.
207
215
  *
@@ -212,8 +220,10 @@ export declare class CrmPipeline extends MacroEntity<AccessiblePipeline> {
212
220
  version: number;
213
221
  }>;
214
222
  /**
215
- * Add a CSV's rows as entries: CSV text, or a CSV document. Columns match
216
- * fields by name; Company and Domain (or Contact and Email) name each row's
223
+ * Import CSV entries into a company or contact pipeline; generic pipelines are refused.
224
+ *
225
+ * Accepts CSV text or a CSV document. Columns match fields by name;
226
+ * Company and Domain (or Contact and Email) name each row's
217
227
  * record, created when the team lacks it. Records already here are not
218
228
  * added again, and select options the CSV needs are added.
219
229
  *
@@ -221,9 +231,12 @@ export declare class CrmPipeline extends MacroEntity<AccessiblePipeline> {
221
231
  */
222
232
  importCsv(source: string | Document): Promise<PipelineImport>;
223
233
  /**
224
- * Every entry as CSV text: Company and Domain (or Contact and Email), then
225
- * one column per field, people as emails; {@link CrmPipeline.importCsv}
226
- * reads the same layout. `complete` is false past 5000 entries.
234
+ * Export up to 5000 entries as CSV; check `complete` before treating it as a full export.
235
+ *
236
+ * Company and contact pipelines export Company and Domain (or Contact and
237
+ * Email), then one column per field, with people as emails. Generic
238
+ * pipelines export only their fields. {@link CrmPipeline.importCsv} accepts
239
+ * the company or contact layout; generic pipelines refuse CSV imports.
227
240
  *
228
241
  * @readonly
229
242
  */
@@ -233,7 +246,10 @@ export declare class CrmPipeline extends MacroEntity<AccessiblePipeline> {
233
246
  rows: number;
234
247
  complete: boolean;
235
248
  }>;
236
- /** Save every entry as a CSV file in the caller's Macro files, laid out as {@link CrmPipeline.exportCsv} returns it.
249
+ /**
250
+ * Save up to 5000 entries as a CSV file; check `complete` before treating it as a full export.
251
+ *
252
+ * Saved in the caller's Macro files, laid out as {@link CrmPipeline.exportCsv} returns it.
237
253
  *
238
254
  * @write
239
255
  */
@@ -242,7 +258,10 @@ export declare class CrmPipeline extends MacroEntity<AccessiblePipeline> {
242
258
  rows: number;
243
259
  complete: boolean;
244
260
  }>;
245
- /** @internal Whether entries track companies or contacts; `undefined` for a generic pipeline. */
261
+ /**
262
+ * @internal Whether entries track companies or contacts; `undefined` for a generic pipeline.
263
+ * Writes read it first, so a failed read cannot hide a committed write that a retry would repeat.
264
+ */
246
265
  private trackedRecordType;
247
266
  /** Apply an atomic generated database operation batch through this pipeline.
248
267
  * As with Database.applyOps, batch-local UUIDs may name resources minted earlier in the batch.
@@ -300,11 +319,11 @@ export declare class PipelineTable extends MacroEntity<TableDetail> {
300
319
  */
301
320
  rowById(id: string): PipelineRow;
302
321
  /**
303
- * Rows from the authorized pipeline surface.
322
+ * Rows from the authorized pipeline surface; `maxItems` caps the total.
304
323
  *
305
324
  * @readonly
306
325
  */
307
- rows(): AsyncGenerator<PipelineRow>;
326
+ rows(opts?: IterationOptions): AsyncGenerator<PipelineRow>;
308
327
  }
309
328
  /**
310
329
  * A view owned and authorized by its CRM pipeline.
@@ -1,9 +1,9 @@
1
- import type { CreatePipeline } from '../../../generated/storage/types.gen';
1
+ import type { CreatePipelineRequest } from '../../../generated/storage/types.gen';
2
2
  import type { MacroClient } from '../../utils/client';
3
3
  import type { Company } from './company';
4
4
  import type { Contact } from './contact';
5
5
  import { CrmPipeline } from './pipeline';
6
- import { PipelineEntry } from './pipeline-entry';
6
+ import { PipelineEntry, type PipelineField } from './pipeline-entry';
7
7
  /** CRM pipelines in the caller's team. */
8
8
  export declare class PipelineNamespace {
9
9
  private readonly client;
@@ -17,11 +17,37 @@ export declare class PipelineNamespace {
17
17
  */
18
18
  list(): Promise<CrmPipeline[]>;
19
19
  /**
20
- * Create a pipeline and its backing storage.
20
+ * List accessible pipelines with each one's fields in column order and its
21
+ * version, in one call. A select field lists its options, so Stage lists the
22
+ * pipeline's stages from first to last; a tracked pipeline's first field
23
+ * names its company or contact. Use it instead of reading each pipeline's
24
+ * table or running a `find` per pipeline just to learn its fields.
25
+ *
26
+ * @readonly
27
+ */
28
+ listWithFields(): Promise<{
29
+ pipeline: CrmPipeline;
30
+ fields: PipelineField[];
31
+ version: number;
32
+ }[]>;
33
+ /**
34
+ * Create a pipeline. A company or contact pipeline starts with its record,
35
+ * Stage, Owner and Revenue fields; a generic one (no `recordType`) with
36
+ * only Name. `stages` (first to last) replaces the team's default stages,
37
+ * or adds a Stage field to a generic pipeline; `fields` are added after the
38
+ * standard ones. Private unless `sharing` is `team`.
39
+ *
40
+ * @example
41
+ * await macro.crm.pipelines.create({
42
+ * name: 'Hiring',
43
+ * recordType: 'contact',
44
+ * stages: ['Sourced', 'Interview', 'Offer', 'Hired'],
45
+ * fields: [{ name: 'Role', type: 'select', options: ['Engineer', 'Designer'] }],
46
+ * });
21
47
  *
22
48
  * @write
23
49
  */
24
- create(options: CreatePipeline): Promise<CrmPipeline>;
50
+ create(options: CreatePipelineRequest): Promise<CrmPipeline>;
25
51
  /**
26
52
  * Every entry (deal) tracking one of these companies or contacts, across
27
53
  * the caller's pipelines; pipelines without one are left out.
@@ -33,7 +59,9 @@ export declare class PipelineNamespace {
33
59
  entries: PipelineEntry[];
34
60
  }[]>;
35
61
  /**
36
- * Entries (deals) whose company or contact name, domain or email contains
62
+ * Search entries across the caller's pipelines.
63
+ *
64
+ * Returns entries (deals) whose company or contact name, domain or email contains
37
65
  * `search`, across the caller's pipelines; pipelines without a match are
38
66
  * left out.
39
67
  *