@base44-preview/sdk 0.8.48-pr.289.c93657a → 0.8.49-pr.289.54867b1
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.
- package/dist/index.d.ts +1 -1
- package/dist/modules/actors.types.d.ts +25 -42
- package/dist/modules/entities.js +64 -27
- package/dist/modules/entities.types.d.ts +291 -8
- package/dist/utils/axios-client.js +4 -5
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -4,7 +4,7 @@ import { getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl } from
|
|
|
4
4
|
export { createClient, createClientFromRequest, Base44Error, getAccessToken, saveAccessToken, removeAccessToken, getLoginUrl, };
|
|
5
5
|
export type { Base44Client, CreateClientAnalyticsConfig, CreateClientConfig, CreateClientOptions, Base44ErrorJSON, };
|
|
6
6
|
export * from "./types.js";
|
|
7
|
-
export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityRecord, EntityTypeRegistry, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
|
|
7
|
+
export type { DeleteManyResult, DeleteResult, EntitiesModule, EntityAggregateResult, EntityAggregateSpec, EntityDateBucketUnit, EntityDistinctOptions, EntityFilterOperators, EntityFilterQuery, EntityFilterValue, EntityHandler, EntityListOptions, EntityPage, EntityRecord, EntityTypeRegistry, EntityUpsertOptions, EntityUpsertResult, ImportResult, RealtimeEventType, RealtimeEvent, RealtimeCallback, SortField, UpdateManyResult, } from "./modules/entities.types.js";
|
|
8
8
|
export type { AuthModule, LoginResponse, RegisterParams, VerifyOtpParams, ChangePasswordParams, ResetPasswordParams, User, } from "./modules/auth.types.js";
|
|
9
9
|
export type { IntegrationsModule, IntegrationEndpointFunction, CoreIntegrations, InvokeLLMParams, GenerateImageParams, GenerateImageResult, UploadFileParams, UploadFileResult, SendEmailParams, SendEmailResult, ExtractDataFromUploadedFileParams, ExtractDataFromUploadedFileResult, UploadPrivateFileParams, UploadPrivateFileResult, CreateFileSignedUrlParams, CreateFileSignedUrlResult, } from "./modules/integrations.types.js";
|
|
10
10
|
export type { FunctionsModule, FunctionName, FunctionNameRegistry, } from "./modules/functions.types.js";
|
|
@@ -6,6 +6,11 @@
|
|
|
6
6
|
* defines incoming messages that a client sends to the actor. `toClient` defines
|
|
7
7
|
* outgoing messages that the actor sends to connected clients.
|
|
8
8
|
*
|
|
9
|
+
* To generate types from deployed actors instead, use the
|
|
10
|
+
* [`types generate`](/developers/references/cli/commands/types-generate) CLI command.
|
|
11
|
+
* See [Typing messages in the client](/developers/backend/resources/actors/overview#typing-messages-in-the-client)
|
|
12
|
+
* for how to define your message types.
|
|
13
|
+
*
|
|
9
14
|
* @example
|
|
10
15
|
* ```typescript
|
|
11
16
|
* declare module "@base44/sdk" {
|
|
@@ -21,7 +26,8 @@
|
|
|
21
26
|
export interface ActorRegistry {
|
|
22
27
|
}
|
|
23
28
|
/**
|
|
24
|
-
* Lists actor names when your project includes types generated by the CLI
|
|
29
|
+
* Lists actor names when your project includes types generated by the CLI
|
|
30
|
+
* with [`types generate`](/developers/references/cli/commands/types-generate).
|
|
25
31
|
*
|
|
26
32
|
* The generated names provide autocomplete for deployed actors. To define
|
|
27
33
|
* incoming and outgoing message types manually, augment {@link ActorRegistry}.
|
|
@@ -42,9 +48,11 @@ export interface ActorConnectOptions {
|
|
|
42
48
|
/**
|
|
43
49
|
* Connection ID that the actor receives as `conn.id`.
|
|
44
50
|
*
|
|
45
|
-
*
|
|
46
|
-
*
|
|
47
|
-
*
|
|
51
|
+
* Use a stable value, such as one stored per browser tab, so the actor
|
|
52
|
+
* can recognize the same client if it reconnects. If omitted, the SDK generates one.
|
|
53
|
+
*
|
|
54
|
+
* See [Connection ID](/developers/backend/resources/actors/overview#connection-id)
|
|
55
|
+
* for more details.
|
|
48
56
|
*/
|
|
49
57
|
id?: string;
|
|
50
58
|
}
|
|
@@ -55,12 +63,6 @@ export interface ActorConnectOptions {
|
|
|
55
63
|
export interface ActorSubscription {
|
|
56
64
|
/**
|
|
57
65
|
* Removes this listener. Other listeners and the socket stay open.
|
|
58
|
-
*
|
|
59
|
-
* @example
|
|
60
|
-
* ```typescript
|
|
61
|
-
* const sub = conn.subscribe((msg) => console.log(msg));
|
|
62
|
-
* sub.unsubscribe();
|
|
63
|
-
* ```
|
|
64
66
|
*/
|
|
65
67
|
unsubscribe(): void;
|
|
66
68
|
}
|
|
@@ -80,14 +82,6 @@ export interface Connection<N extends string = string> {
|
|
|
80
82
|
*
|
|
81
83
|
* @param callback - Called with each outgoing message sent to this connection.
|
|
82
84
|
* @returns A handle you can use to remove this listener without closing the socket.
|
|
83
|
-
*
|
|
84
|
-
* @example
|
|
85
|
-
* ```typescript
|
|
86
|
-
* const conn = base44.actors.Chat("session-1").connect();
|
|
87
|
-
* const sub = conn.subscribe((msg) => {
|
|
88
|
-
* if (msg.type === "message") console.log(msg.text);
|
|
89
|
-
* });
|
|
90
|
-
* ```
|
|
91
85
|
*/
|
|
92
86
|
subscribe(callback: (data: ToClientFor<N>) => void): ActorSubscription;
|
|
93
87
|
/**
|
|
@@ -97,11 +91,6 @@ export interface Connection<N extends string = string> {
|
|
|
97
91
|
* drops further sends.
|
|
98
92
|
*
|
|
99
93
|
* @param data - Incoming message to send. Typed through {@link ActorRegistry} when configured.
|
|
100
|
-
*
|
|
101
|
-
* @example
|
|
102
|
-
* ```typescript
|
|
103
|
-
* conn.send({ type: "message", text: "Hello" });
|
|
104
|
-
* ```
|
|
105
94
|
*/
|
|
106
95
|
send(data: ToServerFor<N>): void;
|
|
107
96
|
/**
|
|
@@ -109,11 +98,6 @@ export interface Connection<N extends string = string> {
|
|
|
109
98
|
*
|
|
110
99
|
* Safe to call more than once. A connection also closes itself when it fails
|
|
111
100
|
* permanently. See {@link ActorRef.connect} for how to open a fresh connection.
|
|
112
|
-
*
|
|
113
|
-
* @example
|
|
114
|
-
* ```typescript
|
|
115
|
-
* conn.close();
|
|
116
|
-
* ```
|
|
117
101
|
*/
|
|
118
102
|
close(): void;
|
|
119
103
|
}
|
|
@@ -130,14 +114,11 @@ export interface ActorRef<N extends string = string> {
|
|
|
130
114
|
* failure, such as a missing actor or denied connection, fix the cause and call
|
|
131
115
|
* `connect()` again. Add subscriptions to the new connection.
|
|
132
116
|
*
|
|
117
|
+
* See [Connect a client to a session](/developers/backend/resources/actors/samples#connect-a-client-to-a-session)
|
|
118
|
+
* for a sample flow.
|
|
119
|
+
*
|
|
133
120
|
* @param options - Optional connection settings, such as a stable connection ID.
|
|
134
121
|
* @returns The {@link Connection} for this actor session.
|
|
135
|
-
*
|
|
136
|
-
* @example
|
|
137
|
-
* ```typescript
|
|
138
|
-
* const conn = base44.actors.Chat("session-1").connect({ id: "tab-abc" });
|
|
139
|
-
* conn.subscribe((msg) => console.log(msg));
|
|
140
|
-
* ```
|
|
141
122
|
*/
|
|
142
123
|
connect(options?: ActorConnectOptions): Connection<N>;
|
|
143
124
|
}
|
|
@@ -155,12 +136,6 @@ export interface ActorClient<N extends string = string> {
|
|
|
155
136
|
*
|
|
156
137
|
* @param instanceId - Session ID that identifies which session to connect to.
|
|
157
138
|
* @returns A reference to the actor session.
|
|
158
|
-
*
|
|
159
|
-
* @example
|
|
160
|
-
* ```typescript
|
|
161
|
-
* const session = base44.actors.Chat("lobby-1");
|
|
162
|
-
* const conn = session.connect();
|
|
163
|
-
* ```
|
|
164
139
|
*/
|
|
165
140
|
(instanceId: string): ActorRef<N>;
|
|
166
141
|
}
|
|
@@ -179,8 +154,16 @@ export interface ActorClient<N extends string = string> {
|
|
|
179
154
|
* - Close the connection with {@link Connection.close}.
|
|
180
155
|
*
|
|
181
156
|
* See [Actors Overview](/developers/backend/resources/actors/overview)
|
|
182
|
-
* for actor concepts and terminology,
|
|
183
|
-
* for the backend class API
|
|
157
|
+
* for actor concepts and terminology, [Actor Class Reference](/developers/backend/resources/actors/reference)
|
|
158
|
+
* for the backend class API, and [Sample Flows](/developers/backend/resources/actors/samples)
|
|
159
|
+
* for common patterns.
|
|
160
|
+
*
|
|
161
|
+
* ## See also
|
|
162
|
+
*
|
|
163
|
+
* - [Actors Overview](/developers/backend/resources/actors/overview) — Actor concepts, sessions, message types, storage, and timers
|
|
164
|
+
* - [Actor Class Reference](/developers/backend/resources/actors/reference) — Backend class API
|
|
165
|
+
* - [Sample Flows](/developers/backend/resources/actors/samples) — Connect a client, run ticks, schedule wakes, and persist data
|
|
166
|
+
* - [`types generate`](/developers/references/cli/commands/types-generate) — Generate TypeScript types from deployed actors
|
|
184
167
|
*
|
|
185
168
|
* ## Authentication modes
|
|
186
169
|
*
|
package/dist/modules/entities.js
CHANGED
|
@@ -41,6 +41,10 @@ function parseRealtimeMessage(dataStr) {
|
|
|
41
41
|
return null;
|
|
42
42
|
}
|
|
43
43
|
}
|
|
44
|
+
const DEFAULT_PAGE_LIMIT = 100;
|
|
45
|
+
function isPageOptions(value) {
|
|
46
|
+
return typeof value === "object" && value !== null;
|
|
47
|
+
}
|
|
44
48
|
/**
|
|
45
49
|
* Creates a handler for a specific entity.
|
|
46
50
|
*
|
|
@@ -53,34 +57,51 @@ function parseRealtimeMessage(dataStr) {
|
|
|
53
57
|
*/
|
|
54
58
|
function createEntityHandler(axios, appId, entityName, getSocket) {
|
|
55
59
|
const baseURL = `/apps/${appId}/entities/${entityName}`;
|
|
60
|
+
const fieldsParam = (fields) => Array.isArray(fields) ? fields.join(",") : fields;
|
|
61
|
+
// GET /{entity}: the array form shared by list() and filter()
|
|
62
|
+
const readArray = (sort, limit, skip, fields, query) => {
|
|
63
|
+
const params = {};
|
|
64
|
+
if (query)
|
|
65
|
+
params.q = JSON.stringify(query);
|
|
66
|
+
if (sort)
|
|
67
|
+
params.sort = sort;
|
|
68
|
+
if (limit)
|
|
69
|
+
params.limit = limit;
|
|
70
|
+
if (skip)
|
|
71
|
+
params.skip = skip;
|
|
72
|
+
if (fields)
|
|
73
|
+
params.fields = fieldsParam(fields);
|
|
74
|
+
return axios.get(baseURL, { params });
|
|
75
|
+
};
|
|
76
|
+
// GET /{entity}/v2/list: one cursor page of records or distinct values, shared by list(options) and filter(query, options)
|
|
77
|
+
const readPage = (options, query) => {
|
|
78
|
+
const params = {};
|
|
79
|
+
if (query)
|
|
80
|
+
params.q = JSON.stringify(query);
|
|
81
|
+
params.limit = options.limit || DEFAULT_PAGE_LIMIT;
|
|
82
|
+
if (options.cursor)
|
|
83
|
+
params.cursor = options.cursor;
|
|
84
|
+
if ("distinct" in options) {
|
|
85
|
+
params.distinct = options.distinct;
|
|
86
|
+
}
|
|
87
|
+
else {
|
|
88
|
+
if (options.sort)
|
|
89
|
+
params.sort = options.sort;
|
|
90
|
+
if (options.fields)
|
|
91
|
+
params.fields = fieldsParam(options.fields);
|
|
92
|
+
}
|
|
93
|
+
return axios.get(`${baseURL}/v2/list`, { params });
|
|
94
|
+
};
|
|
56
95
|
return {
|
|
57
|
-
//
|
|
58
|
-
async list(
|
|
59
|
-
const
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
if (fields)
|
|
67
|
-
params.fields = Array.isArray(fields) ? fields.join(",") : fields;
|
|
68
|
-
return axios.get(baseURL, { params });
|
|
69
|
-
},
|
|
70
|
-
// Filter entities based on query
|
|
71
|
-
async filter(query, sort, limit, skip, fields) {
|
|
72
|
-
const params = {
|
|
73
|
-
q: JSON.stringify(query),
|
|
74
|
-
};
|
|
75
|
-
if (sort)
|
|
76
|
-
params.sort = sort;
|
|
77
|
-
if (limit)
|
|
78
|
-
params.limit = limit;
|
|
79
|
-
if (skip)
|
|
80
|
-
params.skip = skip;
|
|
81
|
-
if (fields)
|
|
82
|
-
params.fields = Array.isArray(fields) ? fields.join(",") : fields;
|
|
83
|
-
return axios.get(baseURL, { params });
|
|
96
|
+
// list(sort, limit, skip, fields) returns an array; list(options) returns one cursor page.
|
|
97
|
+
async list(...args) {
|
|
98
|
+
const [sort, limit, skip, fields] = args;
|
|
99
|
+
return isPageOptions(sort) ? readPage(sort) : readArray(sort, limit, skip, fields);
|
|
100
|
+
},
|
|
101
|
+
// filter(query, sort, limit, skip, fields) returns an array; filter(query, options) returns one cursor page.
|
|
102
|
+
async filter(query, ...args) {
|
|
103
|
+
const [sort, limit, skip, fields] = args;
|
|
104
|
+
return isPageOptions(sort) ? readPage(sort, query) : readArray(sort, limit, skip, fields, query);
|
|
84
105
|
},
|
|
85
106
|
// Get entity by ID
|
|
86
107
|
async get(id) {
|
|
@@ -110,6 +131,22 @@ function createEntityHandler(axios, appId, entityName, getSocket) {
|
|
|
110
131
|
async updateMany(query, data) {
|
|
111
132
|
return axios.patch(`${baseURL}/update-many`, { query, data });
|
|
112
133
|
},
|
|
134
|
+
// Count entities matching a query
|
|
135
|
+
async count(query) {
|
|
136
|
+
const params = {};
|
|
137
|
+
if (query)
|
|
138
|
+
params.q = JSON.stringify(query);
|
|
139
|
+
const result = await axios.get(`${baseURL}/count`, { params });
|
|
140
|
+
return result.count;
|
|
141
|
+
},
|
|
142
|
+
// Server-side group-by aggregation
|
|
143
|
+
async aggregate(spec) {
|
|
144
|
+
return axios.post(`${baseURL}/aggregate`, spec);
|
|
145
|
+
},
|
|
146
|
+
// Create or update by a natural key
|
|
147
|
+
async upsert(records, options) {
|
|
148
|
+
return axios.post(`${baseURL}/upsert`, { records, key: options.key });
|
|
149
|
+
},
|
|
113
150
|
// Update multiple entities by ID, each with its own update data
|
|
114
151
|
async bulkUpdate(data) {
|
|
115
152
|
return axios.put(`${baseURL}/bulk`, data);
|
|
@@ -50,6 +50,130 @@ export interface UpdateManyResult {
|
|
|
50
50
|
/** Whether there are more entities matching the query that were not updated in this batch. When `true`, call `updateMany` again with the same query to update the next batch. */
|
|
51
51
|
has_more: boolean;
|
|
52
52
|
}
|
|
53
|
+
/**
|
|
54
|
+
* Options object accepted by {@linkcode EntityHandler.list | list()} and
|
|
55
|
+
* {@linkcode EntityHandler.filter | filter()} to read one cursor page.
|
|
56
|
+
*
|
|
57
|
+
* @typeParam T - Entity record type.
|
|
58
|
+
* @typeParam K - The fields to include in each record.
|
|
59
|
+
*/
|
|
60
|
+
export interface EntityListOptions<T, K extends keyof T = keyof T> {
|
|
61
|
+
/** Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`. */
|
|
62
|
+
sort?: SortField<T>;
|
|
63
|
+
/** Maximum number of records per page, up to 5,000. Defaults to 100. */
|
|
64
|
+
limit?: number;
|
|
65
|
+
/**
|
|
66
|
+
* `next_cursor` from the previous page. Omit or pass `null` for the first page.
|
|
67
|
+
*
|
|
68
|
+
* The token carries the query, sort and fields of the walk, so a later page needs only
|
|
69
|
+
* `cursor` and `limit`. Passing a different query, sort or fields with a cursor is an error.
|
|
70
|
+
*/
|
|
71
|
+
cursor?: string | null;
|
|
72
|
+
/** Array of field names to include in each record. Defaults to all fields. */
|
|
73
|
+
fields?: K[];
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Options object accepted by {@linkcode EntityHandler.list | list()} and
|
|
77
|
+
* {@linkcode EntityHandler.filter | filter()} to read the distinct values of one field
|
|
78
|
+
* instead of records.
|
|
79
|
+
*
|
|
80
|
+
* @typeParam T - Entity record type.
|
|
81
|
+
* @typeParam K - The field whose distinct values to read.
|
|
82
|
+
*/
|
|
83
|
+
export interface EntityDistinctOptions<T, K extends keyof T = keyof T> {
|
|
84
|
+
/** Field whose distinct values to return, in ascending order. Array fields contribute each element. */
|
|
85
|
+
distinct: K;
|
|
86
|
+
/** Maximum number of values per page, up to 1,000. Defaults to 100. */
|
|
87
|
+
limit?: number;
|
|
88
|
+
/** `next_cursor` from the previous page. Omit or pass `null` for the first page. The token carries the query and field. */
|
|
89
|
+
cursor?: string | null;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* One page of records, returned by {@linkcode EntityHandler.list | list()} and
|
|
93
|
+
* {@linkcode EntityHandler.filter | filter()} when called with an options object.
|
|
94
|
+
*
|
|
95
|
+
* @typeParam T - Record type of the items.
|
|
96
|
+
*/
|
|
97
|
+
export interface EntityPage<T> {
|
|
98
|
+
/** The page's records in the requested sort order, or the distinct values in ascending order. */
|
|
99
|
+
items: T[];
|
|
100
|
+
/** Pass as `cursor` to get the next page. `null` on the last page. */
|
|
101
|
+
next_cursor: string | null;
|
|
102
|
+
/** Whether records remain after this page. */
|
|
103
|
+
has_more: boolean;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Time unit for {@linkcode EntityAggregateSpec.dateBucket | dateBucket}.
|
|
107
|
+
*/
|
|
108
|
+
export type EntityDateBucketUnit = "day" | "week" | "month" | "year";
|
|
109
|
+
/**
|
|
110
|
+
* Describes what {@linkcode EntityHandler.aggregate | aggregate()} computes.
|
|
111
|
+
*
|
|
112
|
+
* Name the fields to group by and the measures to compute; the server does the work and
|
|
113
|
+
* returns one row per group. Field names are the entity's own field names.
|
|
114
|
+
*
|
|
115
|
+
* @typeParam T - Entity record type.
|
|
116
|
+
*/
|
|
117
|
+
export interface EntityAggregateSpec<T> {
|
|
118
|
+
/** Filter applied before grouping, in the same form {@linkcode EntityHandler.filter | filter()} accepts. Defaults to all records. */
|
|
119
|
+
query?: EntityFilterQuery<T>;
|
|
120
|
+
/** Field, or up to four fields, to group by. Omit to get one total row. */
|
|
121
|
+
groupBy?: (keyof T & string) | (keyof T & string)[];
|
|
122
|
+
/** Group by a time bucket of a date field. `created_date` and `updated_date` support every unit; date fields of your schema support `day`, `month` and `year`. */
|
|
123
|
+
dateBucket?: {
|
|
124
|
+
field: keyof T & string;
|
|
125
|
+
unit: EntityDateBucketUnit;
|
|
126
|
+
};
|
|
127
|
+
/** Whether to include the number of records per group as `count`. Defaults to `true`. */
|
|
128
|
+
count?: boolean;
|
|
129
|
+
/** Field, or fields, to sum. Each appears in the rows as `sum_<field>`. */
|
|
130
|
+
sum?: (keyof T & string) | (keyof T & string)[];
|
|
131
|
+
/** Field, or fields, to average. Each appears in the rows as `avg_<field>`. */
|
|
132
|
+
avg?: (keyof T & string) | (keyof T & string)[];
|
|
133
|
+
/** Field, or fields, to take the minimum of. Each appears in the rows as `min_<field>`. */
|
|
134
|
+
min?: (keyof T & string) | (keyof T & string)[];
|
|
135
|
+
/** Field, or fields, to take the maximum of. Each appears in the rows as `max_<field>`. */
|
|
136
|
+
max?: (keyof T & string) | (keyof T & string)[];
|
|
137
|
+
/** Field whose distinct values to count per group, returned as `count_distinct_<field>`. */
|
|
138
|
+
countDistinct?: keyof T & string;
|
|
139
|
+
/** Filter on the computed fields, applied after grouping. For example `{ count: { $gt: 1 } }` keeps only duplicated groups. */
|
|
140
|
+
having?: Record<string, any>;
|
|
141
|
+
/** Computed or group field to sort the rows by, with a `-` prefix for descending. For example `'-count'`. */
|
|
142
|
+
sort?: string;
|
|
143
|
+
/** Maximum number of rows, up to 1,000. Defaults to 1,000. */
|
|
144
|
+
limit?: number;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Rows returned by {@linkcode EntityHandler.aggregate | aggregate()}.
|
|
148
|
+
*/
|
|
149
|
+
export interface EntityAggregateResult {
|
|
150
|
+
/** One row per group: the group fields by name, then `count`, `sum_<field>`, `avg_<field>`, `min_<field>`, `max_<field>` or `count_distinct_<field>`. */
|
|
151
|
+
rows: Record<string, any>[];
|
|
152
|
+
/** `true` when more groups exist than `limit` allowed. */
|
|
153
|
+
truncated: boolean;
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Options for {@linkcode EntityHandler.upsert | upsert()}.
|
|
157
|
+
*
|
|
158
|
+
* @typeParam T - Entity record type.
|
|
159
|
+
*/
|
|
160
|
+
export interface EntityUpsertOptions<T> {
|
|
161
|
+
/** Field, or fields, that identify a record. A record whose key values match an existing record updates it; any other record is created. */
|
|
162
|
+
key: (keyof T & string) | (keyof T & string)[];
|
|
163
|
+
}
|
|
164
|
+
/**
|
|
165
|
+
* Result returned by {@linkcode EntityHandler.upsert | upsert()}.
|
|
166
|
+
*
|
|
167
|
+
* @typeParam T - Entity record type.
|
|
168
|
+
*/
|
|
169
|
+
export interface EntityUpsertResult<T = any> {
|
|
170
|
+
/** Number of records that were created. */
|
|
171
|
+
created: number;
|
|
172
|
+
/** Number of existing records that were updated. */
|
|
173
|
+
updated: number;
|
|
174
|
+
/** The written records, created and updated, as they now exist. */
|
|
175
|
+
records: T[];
|
|
176
|
+
}
|
|
53
177
|
/**
|
|
54
178
|
* Result returned when importing entities from a file.
|
|
55
179
|
*
|
|
@@ -211,14 +335,18 @@ export interface EntityHandler<T = any> {
|
|
|
211
335
|
* Retrieves all records of this type with support for sorting,
|
|
212
336
|
* pagination, and field selection.
|
|
213
337
|
*
|
|
214
|
-
* **Note:** The maximum limit is 5,000 items per request.
|
|
338
|
+
* **Note:** The maximum limit is 5,000 items per request. To read more than
|
|
339
|
+
* one page, pass an {@linkcode EntityListOptions | options object} with a
|
|
340
|
+
* `cursor` instead of `skip`: every page costs the same however deep you are,
|
|
341
|
+
* and records deleted between pages never shift the boundary. `skip` is kept
|
|
342
|
+
* for existing code and is deprecated for loops.
|
|
215
343
|
*
|
|
216
344
|
* @typeParam K - The fields to include in the response. Defaults to all fields.
|
|
217
345
|
* @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
|
|
218
|
-
* @param limit - Maximum number of results to return. Defaults to `
|
|
219
|
-
* @param skip - Number of results to skip for pagination. Defaults to `0`.
|
|
346
|
+
* @param limit - Maximum number of results to return. Defaults to `5000`.
|
|
347
|
+
* @param skip - Number of results to skip for pagination. Defaults to `0`. Deprecated for loops; use a cursor.
|
|
220
348
|
* @param fields - Array of field names to include in the response. Defaults to all fields.
|
|
221
|
-
* @returns Promise resolving to an array of records with selected fields.
|
|
349
|
+
* @returns Promise resolving to an array of records with selected fields. When called with an options object, resolves instead to an {@linkcode EntityPage | EntityPage} with `items`, `next_cursor` and `has_more`; with a `distinct` option the items are the field's values.
|
|
222
350
|
*
|
|
223
351
|
* @example
|
|
224
352
|
* ```typescript
|
|
@@ -244,15 +372,39 @@ export interface EntityHandler<T = any> {
|
|
|
244
372
|
* // Get only specific fields
|
|
245
373
|
* const fields = await base44.entities.MyEntity.list('-created_date', 10, 0, ['name', 'status']);
|
|
246
374
|
* ```
|
|
375
|
+
*
|
|
376
|
+
* @example
|
|
377
|
+
* ```typescript
|
|
378
|
+
* // Walk every record with a cursor. Pass an options object instead of
|
|
379
|
+
* // positional arguments to get a page with `next_cursor` and `has_more`.
|
|
380
|
+
* let page = await base44.entities.MyEntity.list({ sort: '-created_date', limit: 1000 });
|
|
381
|
+
* await exportRows(page.items);
|
|
382
|
+
* while (page.has_more) {
|
|
383
|
+
* page = await base44.entities.MyEntity.list({ cursor: page.next_cursor, limit: 1000 });
|
|
384
|
+
* await exportRows(page.items);
|
|
385
|
+
* }
|
|
386
|
+
* ```
|
|
387
|
+
*
|
|
388
|
+
* @example
|
|
389
|
+
* ```typescript
|
|
390
|
+
* // Distinct values of one field, instead of records
|
|
391
|
+
* const { items: categories } = await base44.entities.Product.list({ distinct: 'category' });
|
|
392
|
+
* ```
|
|
247
393
|
*/
|
|
248
394
|
list<K extends keyof T = keyof T>(sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
|
|
395
|
+
list<K extends keyof T>(options: EntityDistinctOptions<T, K>): Promise<EntityPage<T[K]>>;
|
|
396
|
+
list<K extends keyof T = keyof T>(options: EntityListOptions<T, K>): Promise<EntityPage<Pick<T, K>>>;
|
|
249
397
|
/**
|
|
250
398
|
* Filters records based on a query.
|
|
251
399
|
*
|
|
252
400
|
* Retrieves records that match specific criteria with support for
|
|
253
401
|
* sorting, pagination, and field selection.
|
|
254
402
|
*
|
|
255
|
-
* **Note:** The maximum limit is 5,000 items per request.
|
|
403
|
+
* **Note:** The maximum limit is 5,000 items per request. To read more than
|
|
404
|
+
* one page, pass an {@linkcode EntityListOptions | options object} with a
|
|
405
|
+
* `cursor` instead of `skip`: every page costs the same however deep you are,
|
|
406
|
+
* and records deleted between pages never shift the boundary. `skip` is kept
|
|
407
|
+
* for existing code and is deprecated for loops.
|
|
256
408
|
*
|
|
257
409
|
* @typeParam K - The fields to include in the response. Defaults to all fields.
|
|
258
410
|
* @param query - Query object with field-value pairs. Each key should be a field name
|
|
@@ -261,10 +413,10 @@ export interface EntityHandler<T = any> {
|
|
|
261
413
|
* for exact matches, `null` for null values, arrays as shorthand for matching any of the
|
|
262
414
|
* provided values, or documented MongoDB query operators for advanced filtering.
|
|
263
415
|
* @param sort - Sort parameter, such as `'-created_date'` for descending. Defaults to `'-created_date'`.
|
|
264
|
-
* @param limit - Maximum number of results to return. Defaults to `
|
|
265
|
-
* @param skip - Number of results to skip for pagination. Defaults to `0`.
|
|
416
|
+
* @param limit - Maximum number of results to return. Defaults to `5000`.
|
|
417
|
+
* @param skip - Number of results to skip for pagination. Defaults to `0`. Deprecated for loops; use a cursor.
|
|
266
418
|
* @param fields - Array of field names to include in the response. Defaults to all fields.
|
|
267
|
-
* @returns Promise resolving to an array of filtered records with selected fields.
|
|
419
|
+
* @returns Promise resolving to an array of filtered records with selected fields. When called with an options object, resolves instead to an {@linkcode EntityPage | EntityPage} with `items`, `next_cursor` and `has_more`; with a `distinct` option the items are the field's values.
|
|
268
420
|
*
|
|
269
421
|
* @example
|
|
270
422
|
* ```typescript
|
|
@@ -341,8 +493,34 @@ export interface EntityHandler<T = any> {
|
|
|
341
493
|
* ['name', 'priority']
|
|
342
494
|
* );
|
|
343
495
|
* ```
|
|
496
|
+
*
|
|
497
|
+
* @example
|
|
498
|
+
* ```typescript
|
|
499
|
+
* // Walk all matching records with a cursor. Pass an options object as the
|
|
500
|
+
* // second argument to get a page with `next_cursor` and `has_more`.
|
|
501
|
+
* let page = await base44.entities.Order.filter(
|
|
502
|
+
* { status: 'open' },
|
|
503
|
+
* { sort: '-created_date', limit: 1000 }
|
|
504
|
+
* );
|
|
505
|
+
* await exportRows(page.items);
|
|
506
|
+
* while (page.has_more) {
|
|
507
|
+
* page = await base44.entities.Order.filter({ status: 'open' }, { cursor: page.next_cursor, limit: 1000 });
|
|
508
|
+
* await exportRows(page.items);
|
|
509
|
+
* }
|
|
510
|
+
* ```
|
|
511
|
+
*
|
|
512
|
+
* @example
|
|
513
|
+
* ```typescript
|
|
514
|
+
* // Distinct values of one field among the matching records
|
|
515
|
+
* const { items: agents } = await base44.entities.Order.filter(
|
|
516
|
+
* { status: 'open' },
|
|
517
|
+
* { distinct: 'agent_id' }
|
|
518
|
+
* );
|
|
519
|
+
* ```
|
|
344
520
|
*/
|
|
345
521
|
filter<K extends keyof T = keyof T>(query: EntityFilterQuery<T>, sort?: SortField<T>, limit?: number, skip?: number, fields?: K[]): Promise<Pick<T, K>[]>;
|
|
522
|
+
filter<K extends keyof T>(query: EntityFilterQuery<T>, options: EntityDistinctOptions<T, K>): Promise<EntityPage<T[K]>>;
|
|
523
|
+
filter<K extends keyof T = keyof T>(query: EntityFilterQuery<T>, options: EntityListOptions<T, K>): Promise<EntityPage<Pick<T, K>>>;
|
|
346
524
|
/**
|
|
347
525
|
* Gets a single record by ID.
|
|
348
526
|
*
|
|
@@ -549,6 +727,111 @@ export interface EntityHandler<T = any> {
|
|
|
549
727
|
* ```
|
|
550
728
|
*/
|
|
551
729
|
updateMany(query: Partial<T>, data: Record<string, Record<string, any>>): Promise<UpdateManyResult>;
|
|
730
|
+
/**
|
|
731
|
+
* Counts the records that match a query.
|
|
732
|
+
*
|
|
733
|
+
* Returns the number of records the current user can read, without fetching them.
|
|
734
|
+
* Use it for totals, badges and "page N of M" instead of listing records and
|
|
735
|
+
* measuring the array.
|
|
736
|
+
*
|
|
737
|
+
* @param query - Filter query, in the same form {@linkcode filter | filter()} accepts. Defaults to all records.
|
|
738
|
+
* @returns Promise resolving to the number of matching records.
|
|
739
|
+
*
|
|
740
|
+
* @example
|
|
741
|
+
* ```typescript
|
|
742
|
+
* // How many tasks are still open?
|
|
743
|
+
* const open = await base44.entities.Task.count({ status: 'open' });
|
|
744
|
+
* ```
|
|
745
|
+
*
|
|
746
|
+
* @example
|
|
747
|
+
* ```typescript
|
|
748
|
+
* // Total records in the entity
|
|
749
|
+
* const total = await base44.entities.Task.count();
|
|
750
|
+
* ```
|
|
751
|
+
*/
|
|
752
|
+
count(query?: EntityFilterQuery<T>): Promise<number>;
|
|
753
|
+
/**
|
|
754
|
+
* Computes counts, sums, averages, minimums, maximums or distinct counts, grouped by fields.
|
|
755
|
+
*
|
|
756
|
+
* Use it for dashboards, leaderboards and reports instead of loading every record
|
|
757
|
+
* and adding up in the browser. The server groups the records you can read and
|
|
758
|
+
* returns one row per group, up to 1,000 rows.
|
|
759
|
+
*
|
|
760
|
+
* @param spec - What to group by and what to compute. See {@linkcode EntityAggregateSpec | EntityAggregateSpec}.
|
|
761
|
+
* @returns Promise resolving to the rows and a `truncated` flag.
|
|
762
|
+
*
|
|
763
|
+
* @example
|
|
764
|
+
* ```typescript
|
|
765
|
+
* // Sales per agent this month, biggest first
|
|
766
|
+
* const { rows } = await base44.entities.Sale.aggregate({
|
|
767
|
+
* query: { sale_date: { $gte: '2026-09-01' } },
|
|
768
|
+
* groupBy: 'agent_id',
|
|
769
|
+
* sum: 'amount',
|
|
770
|
+
* sort: '-sum_amount'
|
|
771
|
+
* });
|
|
772
|
+
* // rows: [{ agent_id: 'a1', count: 42, sum_amount: 18250 }, ...]
|
|
773
|
+
* ```
|
|
774
|
+
*
|
|
775
|
+
* @example
|
|
776
|
+
* ```typescript
|
|
777
|
+
* // Records created per day
|
|
778
|
+
* const { rows } = await base44.entities.Visit.aggregate({
|
|
779
|
+
* dateBucket: { field: 'created_date', unit: 'day' }
|
|
780
|
+
* });
|
|
781
|
+
* ```
|
|
782
|
+
*
|
|
783
|
+
* @example
|
|
784
|
+
* ```typescript
|
|
785
|
+
* // Find duplicated external ids
|
|
786
|
+
* const { rows } = await base44.entities.Contact.aggregate({
|
|
787
|
+
* groupBy: 'external_id',
|
|
788
|
+
* having: { count: { $gt: 1 } }
|
|
789
|
+
* });
|
|
790
|
+
* ```
|
|
791
|
+
*
|
|
792
|
+
* @example
|
|
793
|
+
* ```typescript
|
|
794
|
+
* // Unique visitors per page
|
|
795
|
+
* const { rows } = await base44.entities.PageView.aggregate({
|
|
796
|
+
* groupBy: 'path',
|
|
797
|
+
* countDistinct: 'session_id'
|
|
798
|
+
* });
|
|
799
|
+
* ```
|
|
800
|
+
*/
|
|
801
|
+
aggregate(spec: EntityAggregateSpec<T>): Promise<EntityAggregateResult>;
|
|
802
|
+
/**
|
|
803
|
+
* Creates or updates records by a key of your own.
|
|
804
|
+
*
|
|
805
|
+
* Use this when you sync data from another system: name the field, or fields, that
|
|
806
|
+
* identify a record, and the server updates the records whose key already exists and
|
|
807
|
+
* creates the rest, in one call. You no longer need to list existing records to check
|
|
808
|
+
* for duplicates before writing.
|
|
809
|
+
*
|
|
810
|
+
* You can upsert up to 500 records per request. When two records in one call share a
|
|
811
|
+
* key, the last one wins. Updates merge the given fields into the existing record, like
|
|
812
|
+
* {@linkcode update | update()}.
|
|
813
|
+
*
|
|
814
|
+
* @param records - Array of record data objects. Each must carry a value for every key field.
|
|
815
|
+
* @param options - The key field or fields. See {@linkcode EntityUpsertOptions | EntityUpsertOptions}.
|
|
816
|
+
* @returns Promise resolving to the counts and the written records.
|
|
817
|
+
*
|
|
818
|
+
* @example
|
|
819
|
+
* ```typescript
|
|
820
|
+
* // Sync contacts from a CRM by their CRM id
|
|
821
|
+
* const result = await base44.entities.Contact.upsert(
|
|
822
|
+
* crmContacts.map(c => ({ crm_id: c.id, name: c.name, email: c.email })),
|
|
823
|
+
* { key: 'crm_id' }
|
|
824
|
+
* );
|
|
825
|
+
* console.log(`${result.created} new, ${result.updated} updated`);
|
|
826
|
+
* ```
|
|
827
|
+
*
|
|
828
|
+
* @example
|
|
829
|
+
* ```typescript
|
|
830
|
+
* // Compound key
|
|
831
|
+
* await base44.entities.Inventory.upsert(rows, { key: ['sku', 'warehouse'] });
|
|
832
|
+
* ```
|
|
833
|
+
*/
|
|
834
|
+
upsert(records: Partial<T>[], options: EntityUpsertOptions<T>): Promise<EntityUpsertResult<T>>;
|
|
552
835
|
/**
|
|
553
836
|
* Updates the specified records in a single request, each with its own data.
|
|
554
837
|
*
|
|
@@ -187,11 +187,10 @@ export function createAxiosClient({ baseURL, headers = {}, token, interceptRespo
|
|
|
187
187
|
}
|
|
188
188
|
return response.data;
|
|
189
189
|
}, (error) => {
|
|
190
|
-
var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m
|
|
191
|
-
const
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
const base44Error = new Base44Error(message, (_e = error.response) === null || _e === void 0 ? void 0 : _e.status, (_m = (_h = (_g = (_f = error.response) === null || _f === void 0 ? void 0 : _f.data) === null || _g === void 0 ? void 0 : _g.code) !== null && _h !== void 0 ? _h : (_l = (_k = (_j = error.response) === null || _j === void 0 ? void 0 : _j.headers) === null || _k === void 0 ? void 0 : _k.get) === null || _l === void 0 ? void 0 : _l.call(_k, "x-base44-connector-error")) !== null && _m !== void 0 ? _m : (_p = (_o = error.response) === null || _o === void 0 ? void 0 : _o.headers) === null || _p === void 0 ? void 0 : _p["x-base44-connector-error"], (_q = error.response) === null || _q === void 0 ? void 0 : _q.data, error);
|
|
190
|
+
var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
|
|
191
|
+
const data = (_a = error.response) === null || _a === void 0 ? void 0 : _a.data;
|
|
192
|
+
const message = ((_b = data === null || data === void 0 ? void 0 : data.error) === null || _b === void 0 ? void 0 : _b.message) || (data === null || data === void 0 ? void 0 : data.message) || (data === null || data === void 0 ? void 0 : data.detail) || error.message;
|
|
193
|
+
const base44Error = new Base44Error(message, (_c = error.response) === null || _c === void 0 ? void 0 : _c.status, (_k = (_f = (_e = (_d = data === null || data === void 0 ? void 0 : data.error) === null || _d === void 0 ? void 0 : _d.code) !== null && _e !== void 0 ? _e : data === null || data === void 0 ? void 0 : data.code) !== null && _f !== void 0 ? _f : (_j = (_h = (_g = error.response) === null || _g === void 0 ? void 0 : _g.headers) === null || _h === void 0 ? void 0 : _h.get) === null || _j === void 0 ? void 0 : _j.call(_h, "x-base44-connector-error")) !== null && _k !== void 0 ? _k : (_m = (_l = error.response) === null || _l === void 0 ? void 0 : _l.headers) === null || _m === void 0 ? void 0 : _m["x-base44-connector-error"], data, error);
|
|
195
194
|
// Log errors in development
|
|
196
195
|
if (process.env.NODE_ENV !== "production") {
|
|
197
196
|
safeErrorLog("[Base44 SDK Error]", base44Error);
|