@casual-simulation/aux-runtime 3.7.0 → 3.7.1-alpha.17809973136

package/runtime/AuxLibraryDefinitions.def

@@ -3597,6 +3597,84 @@ export interface RevokePermissionFailure {
     errorMessage: string;
 }
 
+/**
+ * Represents a request to list permissions for a record.
+ *
+ * @dochash types/permissions
+ * @docname ListPermissionsRequest
+ */
+export interface ListPermissionsRequest extends RecordActionOptions {
+    /**
+     * The name of the record to list permissions for.
+     */
+    recordName: string;
+
+    /**
+     * The marker  to list permissions for.
+     */
+    marker?: string;
+
+    /**
+     * The kind of resource to list permissions for.
+     */
+    resourceKind?: string;
+
+    /**
+     * The ID of the resource to list permissions for.
+     */
+    resourceId?: string;
+}
+
+/**
+ * Represents the result of a request to list permissions for a record.
+ * 
+ * @dochash types/permissions
+ * @docname ListPermissionsResult
+ */
+export type ListPermissionsResult =
+    | ListPermissionsSuccess
+    | ListPermissionsFailure;
+
+/**
+ * Represents a successful response to a request to list permissions for a record.
+ * 
+ * @dochash types/permissions
+ * @docname ListPermissionsSuccess
+ */
+export interface ListPermissionsSuccess {
+    success: true;
+
+    /**
+     * The name of the record.
+     */
+    recordName: string;
+
+    /**
+     * The list of permissions that apply directly to a resource.
+     */
+    resourcePermissions: ListedResourcePermission[];
+
+    /**
+     * The list of permissions that apply to markers.
+     */
+    markerPermissions: ListedMarkerPermission[];
+}
+
+/**
+ * Represents a failed response to a request to list permissions for a record.
+ * 
+ * @dochash types/permissions
+ * @docname ListPermissionsFailure
+ */
+export interface ListPermissionsFailure {
+    success: false;
+    errorCode:
+        | ServerError
+        | ValidatePublicRecordKeyFailure['errorCode']
+        | AuthorizeSubjectFailure['errorCode'];
+    errorMessage: string;
+}
+
 /**
  * Defines the possible results of revoking a role.
  *
@@ -11158,6 +11236,227 @@ export interface CrudListItemsFailure {
     errorMessage: string;
 }
 
+/**
+ * Defines a record that represents a database that can be queried using SQL.
+ */
+export interface DatabaseRecord extends CrudRecord {}
+
+/**
+ * Defines a statement that can be sent to the database.
+ *
+ * @dochash types/records/database
+ * @docname DatabaseStatement
+ */
+export interface DatabaseStatement {
+    /**
+     * The query text of the statement.
+     */
+    query: string;
+
+    /**
+     * The parameters for the query.
+     */
+    params?: unknown[];
+}
+
+
+export type ErrorType = {
+    errorCode: string;
+    errorMessage: string;
+    [key: string]: any;
+};
+
+export type GenericSuccess<T> = T extends Array<any>
+    ? { success: true; items: T }
+    : T extends object
+    ? {
+          success: true;
+      } & T
+    : {
+          success: true;
+          value: T;
+      };
+
+export type GenericFailure<E extends ErrorType> = {
+    success: false;
+} & E;
+
+export type GenericResult<T, E extends ErrorType> =
+    | GenericSuccess<T>
+    | GenericFailure<E>;
+
+export type SimpleError = {
+    errorCode: KnownErrorCodes;
+    errorMessage: string;
+
+    reason?: any;
+    issues?: Zod.ZodIssue[];
+};
+
+/**
+ * Defines the result of an API query.
+ *
+ * @dochash types/records/database
+ * @docname QueryResult
+ */
+export interface ApiQueryResult {
+    /**
+     * The rows that were returned from the query.
+     */
+    rows: Record<string, any>[];
+
+    /**
+     * The number of rows that were modified by the query.
+     */
+    affectedRowCount: number;
+
+    /**
+     * The ID of the last row that was inserted by the query.
+     */
+    lastInsertId?: number | string;
+}
+
+/**
+ * Defines the result of a batch query.
+ *
+ * @dochash types/records/database
+ * @docname BatchResult
+ */
+export interface BatchResult {
+    /**
+     * The results of the individual statements.
+     */
+    results: ApiQueryResult[];
+}
+
+/**
+ * Represents a connection to a database record.
+ *
+ * @dochash types/records/database
+ * @docname Database
+ *
+ * @example Get a database connection.
+ * const database = os.getDatabase('myRecord', 'myDatabase');
+ */
+export interface ApiDatabase {
+    /**
+     * Constructs a database statement from the given [template string literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).
+     *
+     * Once constructed, the returned statement can be used with `run()` or `batch()`.
+     *
+     * @param templates The string templates.
+     * @param params The parameters to interpolate into the templates.
+     * @returns A database statement.
+     *
+     * @example Create a database statement from a SQL query
+     * const statement = database.sql`SELECT * FROM items`;
+     *
+     * @example Use a parameter in a database statement
+     * const itemId = 'abc';
+     * const statement = database.sql`SELECT * FROM items WHERE id = ${itemId}`;
+     */
+    sql(
+        templates: TemplateStringsArray,
+        ...params: unknown[]
+    ): DatabaseStatement;
+
+    /**
+     * Creates a new database statement from the given SQL and parameters.
+     * @param sql The SQL query string.
+     * @param params The parameters to include in the query.
+     * @returns A new database statement.
+     */
+    statement(sql: string, ...params: unknown[]): DatabaseStatement;
+
+    /**
+     * Runs the given readonly query against the database.
+     * This method requires queries to be read-only. This means that queries can only select data, they cannot insert, update, or delete data.
+     *
+     * Supports [template string literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) for parameterized queries.
+     *
+     * **Warning:** To avoid [SQL Injection attacks](https://en.wikipedia.org/wiki/SQL_injection), always use template literals with expressions. Never use the `+` operator to concatenate strings containing SQL code.
+     *
+     * @param templates The string templates.
+     * @param params The parameters that should be used.
+     * @returns A promise that resolves when the query has completed.
+     *
+     * @example Select all items from a table
+     * const result = await database.query`SELECT * FROM items`;
+     *
+     * @example Use a parameter in a query
+     * const itemId = 'abc';
+     * const result = await database.query`SELECT * FROM items WHERE id = ${itemId}`;
+     */
+    query(
+        templates: TemplateStringsArray,
+        ...params: unknown[]
+    ): Promise<GenericResult<ApiQueryResult, SimpleError>>;
+
+    /**
+     * Runs the given SQL on the database and returns the result.
+     * This method supports read-write queries. This means that queries can be used to select, insert, update, and delete data.
+     *
+     * Supports [template string literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) for parameterized queries.
+     *
+     * **Warning:** To avoid [SQL Injection attacks](https://en.wikipedia.org/wiki/SQL_injection), always use template literals with expressions. Never use the `+` operator to concatenate strings containing SQL code.
+     *
+     * @param templates The string templates.
+     * @param params The parameters that should be used.
+     * @returns A promise that resolves when the SQL has completed.
+     *
+     * @example Insert a new item into a table
+     * const name = "New Item";
+     * const value = 100;
+     * const result = await database.execute`INSERT INTO items (name, value) VALUES (${name}, ${value})`;
+     *
+     */
+    execute(
+        templates: TemplateStringsArray,
+        ...params: unknown[]
+    ): Promise<GenericResult<ApiQueryResult, SimpleError>>;
+    /**
+     * Runs the given statements in a single transaction. Transactions can be used to group multiple statements together.
+     * If one statement fails, then none of the statements will have any effect.
+     *
+     * @param func The function that should be used to build the statements.
+     * @param readonly Whether the statements are read-only. If true, then the statements cannot modify data. Defaults to true.
+     *
+     * @example Run multiple select queries at once
+     * const results = await database.batch([
+     *      database.sql`SELECT * FROM items WHERE id = 'abc'`,
+     *      database.sql`SELECT * FROM items WHERE id = 'def'`,
+     *      database.sql`SELECT * FROM items WHERE id = 'ghi'`,
+     * ]);
+     *
+     * @example Insert multiple items at once
+     * const results = await database.batch([
+     *      database.sql`INSERT INTO items (name, value) VALUES ('Item 1', 100)`,
+     *      database.sql`INSERT INTO items (name, value) VALUES ('Item 2', 200)`,
+     *      database.sql`INSERT INTO items (name, value) VALUES ('Item 3', 300)`,
+     * ], false);
+     */
+    batch(
+        statements: DatabaseStatement[],
+        readonly?: boolean
+    ): Promise<GenericResult<BatchResult, SimpleError>>;
+
+    /**
+     * Runs the given database statement.
+     *
+     * @param statement The statement to run.
+     * @param readonly Whether the statement is read-only. If true, then the statement cannot modify data. Defaults to true.
+     */
+    run(
+        statement: DatabaseStatement,
+        readonly?: boolean
+    ): Promise<GenericResult<ApiQueryResult, SimpleError>>;
+
+    /**
+     * Gets an interface to the database that returns unmodified query results.
+     */
+    get raw(): Omit<ApiDatabase, 'raw'>;
+}
+
 
 export type HandleWebhookResult = HandleWebhookSuccess | HandleWebhookFailure;
 
@@ -14453,6 +14752,39 @@ interface Os {
         options?: RecordActionOptions
     ): Promise<RevokePermissionResult>;
 
+    /**
+     * Gets the list of permissions that have been assigned in the given record.
+     *
+     * @param request the request containing the record name and optional filters.
+     * @param options the options for the operation.
+     *
+     * @example List all permissions in a record.
+     * const result = await os.listPermissions({
+     *     recordName: 'myRecord'
+     * });
+     *
+     * @example List permissions for a specific marker.
+     * const result = await os.listPermissions({
+     *     recordName: 'myRecord',
+     *     marker: 'secret'
+     * });
+     *
+     * @example List permissions for a specific resource.
+     * const result = await os.listPermissions({
+     *     recordName: 'myRecord',
+     *     resourceKind: 'data',
+     *     resourceId: 'address'
+     * });
+     *
+     * @dochash actions/os/records
+     * @docgroup 01-records
+     * @docid os.listPermissions
+     * @docname os.listPermissions
+     */
+    listPermissions(
+        request: ListPermissionsRequest
+    ): Promise<ListPermissionsResult>;
+
     /**
      * Grants the current inst admin permissions in the given record for the rest of the day.
      * @param recordName The name of the record.
@@ -15603,6 +15935,158 @@ interface Os {
         options?: RecordActionOptions
     ): Promise<EraseSearchDocumentResult>;
 
+    /**
+     * Creates or updates a database in the given record.
+     *
+     * Databases are used to store and manage structured data within a record.
+     * They use the [SQL programming language](https://www.sqlite.org/lang.html), which is a powerful programming language designed to manage relational databases.
+     *
+     * Returns a promise that resolves with the result of the operation.
+     *
+     * @param request The request to create or update the database.
+     * @param options the options for the request.
+     * @returns A promise that resolves with the result of the operation.
+     *
+     * @example Record a database.
+     * const result = await os.recordDatabase({
+     *      recordName: 'myRecord',
+     *      address: 'myDatabase',
+     * });
+     *
+     * @example Record a private database
+     * const result = await os.recordDatabase({
+     *      recordName: 'myRecord',
+     *      address: 'myDatabase',
+     *      markers: ['private']
+     * });
+     *
+     *
+     * @doctitle Database Actions
+     * @docsidebar Database
+     * @docdescription Database actions allow you to create and manage databases in your records. Databases enable efficient storage and retrieval of structured data within your records, making it easier to manage and query information.
+     * @dochash actions/os/records/database
+     * @docgroup 02-database
+     * @docname os.recordDatabase
+     * @docid recordDatabase
+     */
+    recordDatabase(
+        request: RecordSearchCollectionApiRequest,
+        options?: RecordActionOptions
+    ): Promise<CrudRecordItemResult>;
+
+    /**
+     * Deletes a database along with all the data in it.
+     *
+     * Returns a promise that resolves with the result of the operation.
+     *
+     * @param recordName The name of the record to delete the database from.
+     * @param address The address of the database to delete.
+     * @param options the options for the request.
+     * @returns A promise that resolves with the result of the operation.
+     *
+     * @example Erase a database
+     * const result = await os.eraseDatabase('recordName', 'myDatabase');
+     *
+     * @dochash actions/os/records/database
+     * @docgroup 02-database
+     * @docname os.eraseDatabase
+     * @docid eraseDatabase
+     */
+    eraseDatabase(
+        recordName: string,
+        address: string,
+        options?: RecordActionOptions
+    ): Promise<CrudRecordItemResult>;
+
+    /**
+     * Lists the databases in a record.
+     *
+     * Returns a promise that resolves with the result of the operation.
+     *
+     * @param recordName The name of the record to delete the search collection from.
+     * @param startingAddress the address that the listing should start after.
+     * @param options the options for the request.
+     * @returns A promise that resolves with the result of the operation.
+     *
+     * @example List databases
+     * const result = await os.listDatabases('recordName', 'myDatabase');
+     *
+     * @dochash actions/os/records/database
+     * @docgroup 02-database
+     * @docname os.listDatabases
+     * @docid listDatabases
+     */
+    listDatabases(
+        recordName: string,
+        startingAddress?: string,
+        options?: ListDataOptions
+    ): Promise<CrudListItemsResult<DatabaseRecord>>;
+
+    /**
+     * Lists the databases in a record by a specific marker.
+     * @param recordName The name of the record to list the databases from.
+     * @param marker The marker to filter the list by.
+     * @param startingAddress The address that the listing should start after.
+     * @param options The options for the request.
+     * @returns A promise that resolves with the result of the operation.
+     *
+     * @example List public read databases
+     * const result = await os.listDatabasesByMarker('recordName', 'publicRead');
+     *
+     * @example List private databases
+     * const result = await os.listDatabasesByMarker('recordName', 'private');
+     *
+     * @dochash actions/os/records/database
+     * @docgroup 02-database
+     * @docname os.listDatabasesByMarker
+     */
+    listDatabasesByMarker(
+        recordName: string,
+        marker: string,
+        startingAddress?: string,
+        options?: ListDataOptions
+    ): Promise<CrudListItemsResult<DatabaseRecord>>;
+
+    /**
+     * Gets basic info about a database from the specified record.
+     *
+     * @param recordName The name of the record to retrieve the database from.
+     * @param address The address of the database to retrieve.
+     * @param options The options for the request.
+     *
+     * @returns A promise that resolves with the result of the operation.
+     *
+     * @example Get a database and query a table
+     * const db = os.getDatabase('myRecord', 'myDatabase');
+     * const result = await db.query`SELECT * FROM myTable`;
+     *
+     * @example Insert a new row
+     * const value1 = 'abc';
+     * const value2 = 123;
+     * const result = await db.execute`INSERT INTO myTable (column1, column2) VALUES (${value1}, ${value2})`;
+     * 
+     * @example Run multiple queries in a transaction
+     * const values = [
+     *   ['apple', 10],
+     *   ['car', 25000],
+     *   ['strawberry', 1],
+     *   ['lego', 5]
+     * ];
+     *
+     * const result = await db.batch(
+     *   values.map(([name, value]) => db.sql`INSERT INTO data (name, value) VALUES (${name}, ${value})`)
+     * );
+     *
+     * @dochash actions/os/records/database
+     * @docgroup 02-database
+     * @docname os.getDatabase
+     */
+    getDatabase(
+        recordName: string,
+        address: string,
+        options?: RecordActionOptions
+    ): ApiDatabase;
+
     /**
      * Gets the list of studios that the currently logged in user has access to.
      * 
@@ -16823,6 +17307,27 @@ interface Experiment {
      * Returns a promise that resolves with the voices.
      */
     getVoices(): Promise<SyntheticVoice[]>;
+
+    /**
+     * Adds a map overlay to the given bot's map form.
+     * @param bot The bot that the overlay should be added to.
+     * @param overlayLayer Configuration for the overlay layer to add.
+     */
+    addBotMapLayer(
+        bot: Bot,
+        overlay: {
+            overlayType: 'geojson';
+            data: any;
+            overlayId?: string;
+        }
+    ): Promise<{ success: boolean, data?: { overlayId: string }, message?: string }>;
+
+    /**
+     * Removes a map overlay from the given bot's map form.
+     * @param bot The bot that the overlay should be removed from.
+     * @param overlayId Id of the overlay to remove.
+     */
+    removeBotMapLayer(bot: Bot, overlayId: string): Promise<{ success: boolean, data?: { overlayId: string }, message?: string }>;
 };
 
 

package/runtime/RecordsEvents.d.ts

@@ -1,6 +1,6 @@
 import type { AIChatMessage, RecordFileFailure, WebhookRecord, NotificationRecord, PushNotificationPayload, GrantEntitlementFailure } from '@casual-simulation/aux-records';
 import type { RecordsClientActions } from '@casual-simulation/aux-records/RecordsClient';
-import type { APPROVED_SYMBOL, AsyncAction, AvailablePermissions, Entitlement, EntitlementFeature, GrantedEntitlementScope, KnownErrorCodes, PublicRecordKeyPolicy, StoredAux } from '@casual-simulation/aux-common';
+import type { APPROVED_SYMBOL, AsyncAction, AvailablePermissions, Entitlement, EntitlementFeature, GrantedEntitlementScope, KnownErrorCodes, PublicRecordKeyPolicy, ResourceKinds, StoredAux } from '@casual-simulation/aux-common';
 import type { CreateRealtimeSessionTokenRequest } from '@casual-simulation/aux-records/AIOpenAIRealtimeInterface';
 import type { PackageRecordVersionKey, PackageRecordVersionKeySpecifier, PackageRecordVersionWithMetadata } from '@casual-simulation/aux-records/packages/version';
 export type RecordsActions = RecordsAsyncActions;
@@ -1175,6 +1175,36 @@ export declare function grantRecordPermission(recordName: string, permission: Av
  * @param taskId The ID of the task.
  */
 export declare function revokeRecordPermission(recordName: string, permissionId: string, options: RecordActionOptions, taskId: number | string): RevokeRecordPermissionAction;
+/**
+ * Represents a request to list permissions for a record.
+ *
+ * @dochash types/permissions
+ * @docname ListPermissionsRequest
+ */
+export interface ListPermissionsRequest extends RecordActionOptions {
+    /**
+     * The name of the record to list permissions for.
+     */
+    recordName: string;
+    /**
+     * The marker  to list permissions for.
+     */
+    marker?: string;
+    /**
+     * The kind of resource to list permissions for.
+     */
+    resourceKind?: ResourceKinds;
+    /**
+     * The ID of the resource to list permissions for.
+     */
+    resourceId?: string;
+}
+/**
+ * Creates a RecordsCallProcedureAction to list permissions for a record.
+ * @param request The request options.
+ * @param taskId The ID of the task.
+ */
+export declare function listPermissions(request: ListPermissionsRequest, taskId: number | string): RecordsCallProcedureAction;
 /**
  * Creates a GrantRoleAction for a user.
  * @param recordName The name of the record.
@@ -1476,6 +1506,13 @@ export declare function listInstalledPackages(options: RecordActionOptions, task
  * @param taskId The ID of the task.
  */
 export declare function listUserStudios(options: RecordActionOptions, taskId?: number | string): ListUserStudiosAction;
+/**
+ * Creates a RecordsCallProcedureAction to list the records in a studio.
+ * @param studioId The ID of the studio.
+ * @param options The options that should be used for the action.
+ * @param taskId The ID of the task.
+ */
+export declare function listStudioRecords(studioId: string, options: RecordActionOptions, taskId?: number | string): RecordsCallProcedureAction;
 /**
  * Creates a new JoinRoomAction.
  * @param roomName The name of the room.
@@ -1518,6 +1555,23 @@ export declare function getRoomTrackOptions(roomName: string, address: string, t
  * @param taskId The ID of the task.
  */
 export declare function setRoomTrackOptions(roomName: string, address: string, options: SetRoomTrackOptions, taskId?: number | string): SetRoomTrackOptionsAction;
+/**
+ * Creates an action that is able to list the insts in a record.
+ * @param recordName The name of the record.
+ * @param startingInst The inst that the list should start with.
+ * @param options The options.
+ * @param taskId The ID of the async task.
+ */
+export declare function listInsts(recordName: string, startingInst?: string | null, options?: RecordActionOptions, taskId?: number | string): RecordsCallProcedureAction;
+/**
+ * Creates an action that is able to list the insts in a record with the given marker.
+ * @param recordName The name of the record.
+ * @param marker The marker.
+ * @param startingInst The inst that the list should start with.
+ * @param options The options.
+ * @param taskId The ID of the async task.
+ */
+export declare function listInstsByMarker(recordName: string, marker: string, startingInst?: string | null, options?: RecordActionOptions, taskId?: number | string): RecordsCallProcedureAction;
 /**
  * Creates a new GetRoomRemoteOptionsAction.
  * @param roomName The name of the room.

package/runtime/RecordsEvents.js

@@ -153,6 +153,23 @@ export function revokeRecordPermission(recordName, permissionId, options, taskId
         taskId,
     };
 }
+/**
+ * Creates a RecordsCallProcedureAction to list permissions for a record.
+ * @param request The request options.
+ * @param taskId The ID of the task.
+ */
+export function listPermissions(request, taskId) {
+    return recordsCallProcedure({
+        listPermissions: {
+            input: {
+                recordName: request.recordName,
+                marker: request.marker,
+                resourceKind: request.resourceKind,
+                resourceId: request.resourceId,
+            },
+        },
+    }, request, taskId);
+}
 /**
  * Creates a GrantRoleAction for a user.
  * @param recordName The name of the record.
@@ -883,6 +900,21 @@ export function listUserStudios(options, taskId) {
         taskId,
     };
 }
+/**
+ * Creates a RecordsCallProcedureAction to list the records in a studio.
+ * @param studioId The ID of the studio.
+ * @param options The options that should be used for the action.
+ * @param taskId The ID of the task.
+ */
+export function listStudioRecords(studioId, options, taskId) {
+    return recordsCallProcedure({
+        listRecords: {
+            input: {
+                studioId,
+            },
+        },
+    }, options, taskId);
+}
 /**
  * Creates a new JoinRoomAction.
  * @param roomName The name of the room.
@@ -967,6 +999,42 @@ export function setRoomTrackOptions(roomName, address, options, taskId) {
         taskId,
     };
 }
+/**
+ * Creates an action that is able to list the insts in a record.
+ * @param recordName The name of the record.
+ * @param startingInst The inst that the list should start with.
+ * @param options The options.
+ * @param taskId The ID of the async task.
+ */
+export function listInsts(recordName, startingInst, options = {}, taskId) {
+    return recordsCallProcedure({
+        listInsts: {
+            input: {
+                recordName,
+                inst: startingInst,
+            },
+        },
+    }, options, taskId);
+}
+/**
+ * Creates an action that is able to list the insts in a record with the given marker.
+ * @param recordName The name of the record.
+ * @param marker The marker.
+ * @param startingInst The inst that the list should start with.
+ * @param options The options.
+ * @param taskId The ID of the async task.
+ */
+export function listInstsByMarker(recordName, marker, startingInst, options = {}, taskId) {
+    return recordsCallProcedure({
+        listInsts: {
+            input: {
+                recordName,
+                inst: startingInst,
+                marker,
+            },
+        },
+    }, options, taskId);
+}
 /**
  * Creates a new GetRoomRemoteOptionsAction.
  * @param roomName The name of the room.