Skip to main content
Version: Current

Records Actions

  • os.countEvents(recordNameOrKey: string, eventName: string, endpoint: string): Promise<GetCountResult>​

    Gets the number of times that the given event has been recorded in the given record.

    Returns a promise that resolves with an object that indicates whether the operation was successful or unsuccessful.

    The first parameter is a string and is the name of the record that the event count should be retrieved from. It can also be a record key.

    The second parameter is a string and is the name of the event whose count should be retrieved.

    The third parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Get the number of times the click event has happened
    const result = await os.countEvents(myRecord, 'click');

    if (result.success) {
        os.toast(result.count);
    } else {
        os.toast('Failed to get count ' + result.errorMessage);
    }

  • os.eraseData(recordKeyOrName: string, address: string, endpoint: string): Promise<EraseDataResult>​

    Erases the data stored at the given address in the given record. Returns a promise that resolves with an object that contains the data (if successful) or information about the error that occurred.

    The first parameter is a string and is the record key or record name that should be used to access the record. You can request a record key by using os.getPublicRecordKey(name) .

    The second parameter is a string and is the address that the data is stored at.

    The third parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Erase some data from a record
    const recordKeyResult = await os.getPublicRecordKey('myRecord');
    if (!recordKeyResult.success) {
        os.toast("Failed to get a record key! " + recordKeyResult.errorMessage);
        return;
    }
    const result = await os.eraseData(recordKeyResult.recordKey, 'myAddress');

    if (result.success) {
        os.toast("Success!");
    } else {
        os.toast("Failed " + result.errorMessage);
    }

  • os.eraseFile(recordKeyOrName: string, result: RecordFileSuccess, endpoint?: string): Promise<EraseFileResult>​

    Erases the file referenced in the given os.recordFile(recordKeyOrName, data, options, endpoint) result. Returns a promise that resolves with an object that indicates if the file was deleted or if an error occurred.

    The first parameter is a string and is the record key or name that should be used to delete the file.

    The second parameter is a RecordFileSuccess and is the successful result of a os.recordFile() call.

    The third parameter is optional and is a string and is the records endpoint that should be queried. Optional.

    Examples
    Delete a file
    const result = await os.eraseFile(tags.recordKey, recordFileResult);

    if (result.success) {
        os.toast("Success!");
    } else {
        os.toast("Failed " + result.errorMessage);
    }

  • os.eraseFile(recordKeyOrName: string, url: string, endpoint?: string): Promise<EraseFileResult>​

    Erases the file at the given URL. Returns a promise that resolves with an object that indicates if the file was deleted or if an error occurred.

    The first parameter is a string and is the record key or record name that should be used to access the record. You can request a record key by using os.getPublicRecordKey(name) .

    The second parameter is a string and is the URL that the file is stored at.

    The third parameter is optional and is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Delete a file
    const result = await os.eraseFile(tags.recordKey, fileUrl);

    if (result.success) {
        os.toast("Success!");
    } else {
        os.toast("Failed " + result.errorMessage);
    }

  • os.eraseManualApprovalData(recordKeyOrName: string, address: string, endpoint: string): Promise<EraseDataResult>​

    Erases the manual approval data stored at the given address in the given record. Returns a promise that resolves with an object that contains the data (if successful) or information about the error that occurred.

    Works the same as os.eraseData(recordKeyOrName, address, endpoint) except that manual approval data records require the user to allow the operation manually.

    The first parameter is a string and is the record key or record name that should be used to access the record. You can request a record key by using os.getPublicRecordKey(name) .

    The second parameter is a string and is the address that the data is stored at.

    The third parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

  • os.getData(recordKeyOrName: string, address: string, endpoint: string): Promise<GetDataResult>​

    Gets the data stored at the given address in the given record. Returns a promise that resolves with an object that contains the data (if successful) or information about the error that occurred.

    The first parameter is a string and is the record name or a record key. This indicates the record that the data should be retrieved from. Note that you don't need a record key in order to retrieve public data from a record. Using a record name will work just fine.

    The second parameter is a string and is the address that the data should be retrieved from.

    The third parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Get some data from a record
    const result = await os.getData('myRecord', 'myAddress');

    if (result.success) {
        os.toast(result.data);
    } else {
        os.toast("Failed " + result.errorMessage);
    }

  • os.getFile(result: RecordFileSuccess, endpoint?: string): Promise<any>​

    Downloads the file that is specified in the given os.recordFile(recordKeyOrName, data, options, endpoint) result.

    Returns a promise that resolves with the file data.

    The first parameter is a RecordFileSuccess and is the result of a os.recordFile(recordKeyOrName, data, options, endpoint) call.

    The second parameter is optional and is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint. Only used for private files.

    Examples
    Get a file that was uploaded
    const recordKeyResult = await os.getPublicRecordKey('myRecord');
    if (!recordKeyResult.success) {
        os.toast("Failed to get a record key! " + recordKeyResult.errorMessage);
        return;
    }
    const result = await os.recordFile(recordKeyResult.recordKey, getBots("color", "red"), {
        description: 'my bots'
    });

    if (result.success) {
        tags.uploadResult = result;
        os.toast("Success! Uploaded to " + result.url);
    } else {
        os.toast("Failed " + result.errorMessage);
    }

    // Download the file later
    const fileData = await os.getFile(tags.uploadResult);

  • os.getFile(url: string, endpoint?: string): Promise<any>​

    Downloads the file at the given URL.

    Returns a promise that resolves with the file data.

    The first parameter is a string and is the URL that the file is stored at.

    The second parameter is optional and is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint. Only used for private files.

    Examples
    Get a file that was uploaded
    const recordKeyResult = await os.getPublicRecordKey('myRecord');
    if (!recordKeyResult.success) {
        os.toast("Failed to get a record key! " + recordKeyResult.errorMessage);
        return;
    }
    const result = await os.recordFile(recordKeyResult.recordKey, getBots("color", "red"), {
        description: 'my bots'
    });

    if (result.success) {
        tags.uploadUrl = result.url;
        os.toast("Success! Uploaded to " + result.url);
    } else {
        os.toast("Failed " + result.errorMessage);
    }

    // Download the file later
    const fileData = await os.getFile(tags.uploadUrl);

  • os.getManualApprovalData(recordKeyOrName: string, address: string, endpoint: string): Promise<GetDataResult>​

    Gets the manual approval data stored at the given address in the given record.

    Works the same as os.getData(recordKeyOrName, address, endpoint) except that manual approval data records require the user to allow the operation manually.

    The first parameter is a string and is the record name or a record key. This indicates the record that the data should be retrieved from. Note that you don't need a record key in order to retrieve public data from a record. Using a record name will work just fine.

    The second parameter is a string and is the address that the data should be retrieved from.

    The third parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

  • os.getPrivateFile(result: RecordFileSuccess, endpoint?: string): Promise<any>​

    Gets the data stored in the given private file.

    Returns a promise that resolves with the file data.

    The first parameter is a RecordFileSuccess and is the result of a os.recordFile(recordKeyOrName, data, options, endpoint) call.

    The second parameter is optional and is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Get a private file
    const result = await os.getPrivateFile(recordFileResult);

  • os.getPrivateFile(url: string, endpoint?: string): Promise<any>​

    Gets the data stored in the given private file.

    Returns a promise that resolves with the file data.

    The first parameter is a string and is the URL that the file is stored at.

    The second parameter is optional and is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Get a private file
    const fileUrl = 'ENTER_FILE_URL_HERE';
    const result = await os.getPrivateFile(fileUrl);

  • os.getPublicFile(result: RecordFileSuccess): Promise<any>​

    Gets the data stored in the given public file. Only works for files that have the publicRead marker. If the file is not public, then this operation will fail.

    Returns a promise that resolves with the file data.

    The first parameter is a RecordFileSuccess and is the result of a os.recordFile(recordKeyOrName, data, options, endpoint) call.

    Examples
    Get a public file
    const fileData = await os.getFile(recordFileResult);

  • os.getPublicFile(url: string): Promise<any>​

    Gets the data stored in the given public file. Only works for files that have the publicRead marker. If the file is not public, then this operation will fail.

    Returns a promise that resolves with the file data.

    The first parameter is a string and is the URL that the file is stored at.

    Examples
    Get a public file
    let fileUrl = 'ENTER_FILE_URL_HERE';
    const fileData = await os.getFile(fileUrl);

  • os.getPublicRecordKey(name: string): Promise<CreatePublicRecordKeyResult>​

    Requests an access key for the public record with the given name. Returns a promise that resolves with an object that contains the record key (if successful) or information about the error that occurred.

    The first parameter is a string and is the name of the record to get the key for.

    Examples
    Request an access key for a public record.
    const result = await os.getPublicRecordKey('myPublicRecord');

    if (result.success) {
        os.toast(result.recordKey);
    } else {
        os.toast('Failed ' + result.errorMessage);
    }

  • os.getSubjectlessPublicRecordKey(name: string): Promise<CreatePublicRecordKeyResult>​

    Requests an subjectless access key for the public record with the given name. Returns a promise that resolves with an object that contains the record key (if successful) or information about the error that occurred.

    This function works similarly to os.getPublicRecordKey(name), except that it does not require the user to be signed in when the resulting key is used. Usage of subjectless keys should therefore be limited, since they do not record who is using the key and therefore make moderation more difficult.

    The first parameter is a string and is the name of the record.

  • os.grantInstAdminPermission(recordName: string, options?: RecordActionOptions): Promise<GrantRoleResult>​

    Attempts to grant the current inst admin permissions in the given record for the rest of the day.

    When called, the user will be prompted to accept/deny the request.

    See Record Security for more information.

    The first parameter is a string and is the name of the record.

    The second parameter is optional and is a RecordActionOptions and is the options for the operation.

    Examples
    Grant the current inst admin permissions in the "myRecord" record.
    const result = await os.grantInstAdminPermission('myRecord');

  • os.grantInstRole(recordName: string, role: string, inst: string, expireTimeMs: number, options: RecordActionOptions): Promise<GrantRoleResult>​

    Grants the given inst the given role in the given record for the specified time.

    See Record Security for more information.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the role that should be granted.

    The third parameter is a string and is the inst that should be granted the role.

    The fourth parameter is a number and is the time that the role grant expires. If null, then the role will not expire.

    The fifth parameter is a RecordActionOptions and is the options for the operation.

    Examples
    Grant the "myRole" role to a public inst with the name "myInst" in the "myRecord" record.
    const result = await os.grantInstRole('myRecord', 'myRole', '/myInst');
    Grant the "myRole" role to a studio inst with the name "myInst" in the "myRecord" record.
    const result = await os.grantInstRole('myRecord', 'myRole', 'myRecord/myInst');
    Grant a role to an inst for 24 hours.
    const result = await os.grantInstRole('myRecord', 'myRole', 'myInst/myInst', DateTime.now().plus({ hours: 24 }).toMillis());

  • os.grantPermission(recordName: string, permission: AvailablePermissions, options?: RecordActionOptions): Promise<(GrantMarkerPermissionResult | GrantResourcePermissionResult)>​

    Grants the given permission in the given record.

    See Record Security for more information.

    The first parameter is a string and is the name of the record.

    The second parameter is a AvailablePermissions and is the permission that should be added.

    The third parameter is optional and is a RecordActionOptions and is the options for the operation.

    Examples
    Grant a permission in "recordName" to the "myRole" role to access all resources with the "secret" marker.
    const result = await os.grantPermission('recordName', {
        marker: 'secret',

        // any kind of resource
        resourceKind: null,

        // all actions
        action: null,

        subjectType: 'role',
        subjectId: 'myRole',

        options: {},

        // Never expire
        expireTimeMs: null
    });
    Grant a permission to access the data record at "myAddress".
    const result = await os.grantPermission('recordName', {
        resourceKind: 'data',
        resourceId: 'myAddress',

        // all actions
        action: null,

        subjectType: 'role',
        subjectId: 'myRole',

        options: {},

        // Never expire
        expireTimeMs: null
    });

  • os.grantUserRole(recordName: string, role: string, userId: string, expireTimeMs: number, options?: RecordActionOptions): Promise<GrantRoleResult>​

    Grants the given user the given role in the given record for the specified time.

    See Record Security for more information.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the role that should be granted to the user.

    The third parameter is a string and is the ID of the user that should be granted the role.

    The fourth parameter is a number and is the time that the role grant expires. If null , then the role will not expire.

    The fifth parameter is optional and is a RecordActionOptions and is the options for the operation.

    Examples
    Grant the "myRole" role to the user with the ID "myUserId" in the "myRecord" record.
    const result = await os.grantUserRole('myRecord', 'myRole', 'myUserId');
    Grant a role to a user for 24 hours.
    const result = await os.grantUserRole('myRecord', 'myRole', 'myUserId', DateTime.now().plus({ hours: 24 }).toMillis());

  • os.isRecordKey(key: unknown): boolean​

    Determines if the given value represents a record key.

    Returns true if the value is a record key and false if the value is not a record key.

    The first parameter is a unknown and is the value to test to see if it is a record key.

    Examples
    Determine if a value is a record key.
    const isRecordKey = os.isRecordKey(tags.myRecordKey);
    os.toast(tags.myRecordKey ' is ' + (isRecordKey ? 'a' : 'not a') + ' record key.');

  • os.listData(recordKeyOrName: string, startingAddress: string, endpoint: string): Promise<ListDataResult>​

    Gets a partial list of data that is stored in the given record. Optionally accepts the address before the first item that should be included in the list. Returns a promise that resolves with an object that contains the items (if successful) or information about the error that occurred.

    On publicos.link, the returned list is limited to 25 items.

    The first parameter is a string and is the record name or a record key. This indicates the record that the data should be retrieved from. Note that you don't need a record key in order to retrieve public data from a record. Using a record name will work just fine.

    The second parameter is a string and is the address after which items will be included in the list. Since items are ordered within the record by address, this can be used as way to iterate through all the data items in a record. If omitted, then the list will start with the first item.

    The third parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Get a list of data items in a record
    const result = await os.listData('myRecord');
    if (result.success) {
        os.toast(result.items);
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    List all the items in a record
    let lastAddress;
    let items = [];
    while(true) {
        const result = await os.listData('myRecord', lastAddress);
        if (result.success) {
            console.log(result.items);
            items.push(...result.items);
            if (result.items.length > 0) {
                lastAddress = result.items[result.items.length - 1].address;
            } else {
                // result.items is empty, so we can break out of the loop
                break;
            }
        } else {
            os.toast("Failed " + result.errorMessage);
            break;
        }
    }

  • os.listDataByMarker(recordKeyOrName: string, marker: string, startingAddress: string, options: ListDataOptions): Promise<ListDataResult>​

    Gets a partial list of data with the given marker that is stored in the given record. Optionally accepts the address before the first item that should be included in the list. Returns a promise that resolves with an object that contains the items (if successful) or information about the error that occurred.

    The first parameter is a string and is the record name or a record key. This indicates the record that the data should be retrieved from. Note that you don't need a record key in order to retrieve public data from a record. Using a record name will work just fine.

    The second parameter is a string and is the marker that needs to be assigned to the data items that should be included in the list. e.g. Using "publicRead" will return all data items with the "publicRead" marker.

    The third parameter is a string and is the address after which items will be included in the list. Since items are ordered within the record by address, this can be used as way to iterate through all the data items in a record. If omitted, then the list will start with the first item.

    The fourth parameter is a ListDataOptions and is the options for the operation.

    Examples
    Get a list of publicRead data items in a record
    const result = await os.listDataByMarker('myRecord', 'publicRead');
    if (result.success) {
        os.toast(result.items);
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    List all the items that have the publicRead marker in a record
    let lastAddress;
    let items = [];
    while(true) {
        const result = await os.listDataByMarker('myRecord', 'publicRead', lastAddress);
        if (result.success) {
            console.log(result.items);
            items.push(...result.items);
            if (result.items.length > 0) {
                lastAddress = result.items[result.items.length - 1].address;
            } else {
                // result.items is empty, so we can break out of the loop
                break;
            }
        } else {
            os.toast("Failed " + result.errorMessage);
            break;
        }
    }
    List publicRead items in descending order
    const result = await os.listDataByMarker('myRecord', 'publicRead', null, { sort: 'descending' });
    if (result.success) {
        os.toast(result.items);
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    List publicRead items stored at "myContainer" in descending order
    const result = await os.listDataByMarker('myRecord', 'publicRead:myContainer', null, { sort: 'descending' });
    if (result.success) {
        os.toast(result.items);
    } else {
        os.toast("Failed " + result.errorMessage);
    }

  • os.listUserStudios(endpoint?: string): Promise<ListStudiosResult>​

    Gets the list of studios that the currently logged in user has access to.

    Returns a promise that resolves with an object that contains the list of studios (if successful) or information about the error that occurred.

    The first parameter is optional and is a string and is the HTTP Endpoint of the records website that the data should be retrieved from. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Get the list of studios that the user has access to
    const result = await os.listUserStudios();

    if (result.success) {
         os.toast(result.studios.map(s => s.name).join(', '));
    } else {
         os.toast('Failed to get studios ' + result.errorMessage);
    }

  • os.recordData(recordKeyOrRecordName: string, address: string, data: any, endpointOrOptions?: (string | DataRecordOptions)): Promise<RecordDataResult>​

    Stores the given data in the given record at the given address. If data already exists at the given address, it will be overwritten.

    Returns a promise that resolves with an object that indicates if the request was successful.

    The first parameter is a string and is the key that should be used to access the record. You can request a record key by using os.getPublicRecordKey(name) .

    The second parameter is a string and is the address that the data should be stored at.

    The third parameter is a any and is the data that should be stored. This can be any value that can be serialized to JSON. Must be less than 300KB in size. If you need to store data larger than 300KB, you can use os.recordFile(recordKeyOrName, data, options, endpoint) .

    The fourth parameter is optional and is a (string | DataRecordOptions) and is the options that should be used to record the data.

    Examples
    Publish some data to a record
    const recordKeyResult = await os.getPublicRecordKey('myRecord');
    if (!recordKeyResult.success) {
        os.toast("Failed to get a record key! " + recordKeyResult.errorMessage);
        return;
    }
    const result = await os.recordData(recordKeyResult.recordKey, 'myAddress', 'myData');

    if (result.success) {
        os.toast("Success!");
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    Record data to the user's personal record
    const result = await os.recordData(authBot.id, 'myAddress', 'myData');

    if (result.success) {
        os.toast("Success!");
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    Record data with a custom marker
    const result = await os.recordData(authBot.id, 'myAddress', 'myData', {
        marker: 'myMarker'
    });

    if (result.success) {
        os.toast("Success!");
    } else {
        os.toast("Failed " + result.errorMessage);
    }

  • os.recordEvent(recordKeyOrName: string, eventName: string, endpoint: string): Promise<AddCountResult>​

    Records that the given event occurred in the given record.

    Returns a promise that resolves with an object that indicates whether the operation was successful or unsuccessful.

    The first parameter is a string and is the record key or record name that should be used to record the event.

    The second parameter is a string and is the name of the event whose count should be incremented.

    The third parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Record that a click event happened
    await os.recordEvent(myRecordKey, 'click');

  • os.recordFile(recordKeyOrName: string, data: any, options?: RecordFileOptions, endpoint: string): Promise<RecordFileResult>​

    Stores the given file data in the given record using the given options for the file. The file can later be retrieved by using os.getFile(urlOrRecordFileResult).

    Returns a promise that resolves with an object that contains the URL that the file was stored at (if successful) or information about the error that occurred.

    The first parameter is a string and is the record key or record name that should be used to access the record. You can request a record key by using os.getPublicRecordKey(name) .

    The second parameter is a any and is the data that should be stored in the record. This can be a string, an object, a blob, or an ArrayBuffer.

    The third parameter is optional and is a RecordFileOptions and is the options that should be used to record the file.

    The fourth parameter is a string and is the HTTP Endpoint of the records website that the data should be recorded to. If omitted, then the preconfigured records endpoint will be used. Note that when using a custom endpoint, the record key must be a valid record key for that endpoint.

    Examples
    Upload a file
    const files = await os.showUploadFiles();

    if (files.length <= 0) {
        return;
    }

    const file = files[0];
    const result = await os.recordFile(tags.recordKey, file);

    if (result.success) {
        tags.uploadUrl = result.url;
        os.toast("Success! Uploaded to " + result.url);
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    Upload a string to a file record
    const recordKeyResult = await os.getPublicRecordKey('myRecord');
    if (!recordKeyResult.success) {
        os.toast("Failed to get a record key! " + recordKeyResult.errorMessage);
        return;
    }
    const result = await os.recordFile(recordKeyResult.recordKey, 'my file data');

    if (result.success) {
        tags.uploadUrl = result.url;
        os.toast("Success! Uploaded to " + result.url);
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    Upload red bots to a file record
    const recordKeyResult = await os.getPublicRecordKey('myRecord');
    if (!recordKeyResult.success) {
        os.toast("Failed to get a record key! " + recordKeyResult.errorMessage);
        return;
    }
    const result = await os.recordFile(recordKeyResult.recordKey, getBots("color", "red"), {
        description: 'my bots'
    });

    if (result.success) {
        tags.uploadUrl = result.url;
        os.toast("Success! Uploaded to " + result.url);
    } else {
        os.toast("Failed " + result.errorMessage);
    }
    Upload a file to a custom endpoint
    const files = await os.showUploadFiles();

    if (files.length <= 0) {
        return;
    }

    const file = files[0];
    const result = await os.recordFile(tags.recordKey, file, undefined, 'https://myendpoint.com');

    if (result.success) {
        tags.uploadUrl = result.url;
        os.toast("Success! Uploaded to " + result.url);
    } else {
        os.toast("Failed " + result.errorMessage);
    }

  • os.recordManualApprovalData(recordKeyOrRecordName: string, address: string, data: any, endpointOrOptions?: (string | DataRecordOptions)): Promise<RecordDataResult>​

    Stores the given manual approval data in the given record at the given address. If data already exists at the given address, it will be overwritten.

    Returns a promise that resolves with an object that indicates if the request was successful.

    Works the same as os.recordData(recordKeyOrRecordName, address, data, endpointOrOptions) except that manual approval data records require the user to allow the operation manually.

    The first parameter is a string and is the key that should be used to access the record. You can request a record key by using os.getPublicRecordKey(name) .

    The second parameter is a string and is the address that the data should be stored at.

    The third parameter is a any and is the data that should be stored. This can be any value that can be serialized to JSON. Must be less than 300KB in size. If you need to store data larger than 300KB, you can use os.recordFile(recordKeyOrName, data, options, endpoint) .

    The fourth parameter is optional and is a (string | DataRecordOptions) and is the options that should be used to record the data.

  • os.requestAuthBot(): Promise<Bot>​

    Requests that an "authentication" bot be added to the inst for the current browser tab. Auth bots are useful for discovering general information about the logged in user and are typically associated with a https://publicos.link user account.

    Returns a promise that resolves with a bot that contains information about the signed in user session. Resolves with null if the user was unable to sign in.

    On success, the authBot global variable will reference the bot that was returned by the promise.

    See Auth Bot Tags for more information.

    See os.requestAuthBotInBackground() for a version of this function that does not show a popup if the user is not signed in.

    Examples
    Request an auth bot for the user
    await os.requestAuthBot();
    os.toast("Logged in!");

  • os.requestAuthBotInBackground(): Promise<Bot>​

    Requests that an "authentication" bot be added to the inst for the current browser tab. Works similarly to os.requestAuthBot(), except that the request will not show a popup if the user is not signed in.

    Auth bots are useful for discovering general information about the logged in user and are typically associated with a https://publicos.link user account.

    Returns a promise that resolves with a bot that contains information about the signed in user session. Resolves with null if the user is not already signed in.

    On success, the authBot global variable will reference the bot that was returned by the promise.

    See Auth Bot Tags for more information.

    See os.requestAuthBot() for a version of this function that shows a popup if the user is not signed in.

    Examples
    Request the auth bot in the background.
    const authBot = await os.requestAuthBotInBackground();
    if (authBot) {
        os.toast("Logged in!");
    } else {
        os.toast("Not logged in.");
    }

  • os.revokeInstRole(recordName: string, role: string, inst: string, options?: RecordActionOptions): Promise<RevokeRoleResult>​

    Revokes the given role from the given inst in the given record.

    See Record Security for more information.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the role that should be revoked from the inst.

    The third parameter is a string and is the inst that the role should be revoked from.

    The fourth parameter is optional and is a RecordActionOptions and is the options for the operation.

    Examples
    Revoke the "myRole" role from a public inst with the name "myInst" in the "myRecord" record.
    const result = await os.revokeInstRole('myRecord', 'myRole', '/myInst');
    Revoke the "myRole" role from a studio inst with the name "myInst" in the "myRecord" record.
    const result = await os.revokeInstRole('myRecord', 'myRole', 'myRecord/myInst');

  • os.revokePermission(recordName: string, permissionId: string, options?: RecordActionOptions): Promise<RevokeMarkerPermissionResult>​

    Revokes the permission with the given ID from the the given record.

    See Record Security for more information.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the ID of the permission that should be removed.

    The third parameter is optional and is a RecordActionOptions and is the options for the operation.

  • os.revokeUserRole(recordName: string, role: string, userId: string, options?: RecordActionOptions): Promise<RevokeRoleResult>​

    Revokes the given role from the given user in the given record.

    See Record Security for more information.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the role that should be revoked from the user.

    The third parameter is a string and is the ID of the user.

    The fourth parameter is optional and is a RecordActionOptions and is the options for the operation.

    Examples
    Revoke the "myRole" role from the user with the ID "myUserId" in the "myRecord" record.
    const result = await os.revokeUserRole('myRecord', 'myRole', 'myUserId');

  • os.eraseWebhook(recordName: string, address: string, options?: RecordActionOptions): Promise<CrudEraseItemResult>​

    Deletes the webhook from the given record.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address of the webhook.

    The third parameter is optional and is a RecordActionOptions and is the options to use.

  • os.listWebhooks(recordName: string, startingAddress: string, options?: ListWebhooksOptions): Promise<CrudListItemsResult>​

    Lists the webhooks that are in the given record.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address after which items will be included in the list. Since items are ordered within the record by address, this can be used as way to iterate through all the webhooks items in a record. If omitted, then the list will start with the first item.

    The third parameter is optional and is a ListWebhooksOptions and is the options to use.

  • os.listWebhooksByMarker(recordName: string, marker: string, startingAddress: string, options?: ListWebhooksOptions): Promise<CrudListItemsResult>​

    Lists the webhooks that are in the given record.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the marker that needs to be assigned to the data items that should be included in the list. e.g. Using "publicRead" will return all data items with the "publicRead" marker.

    The third parameter is a string and is the address after which items will be included in the list. Since items are ordered within the record by address, this can be used as way to iterate through all the webhooks items in a record. If omitted, then the list will start with the first item.

    The fourth parameter is optional and is a ListWebhooksOptions and is the options to use.

  • os.recordWebhook(recordName: string, webhook: WebhookRecord, options?: RecordActionOptions): Promise<CrudRecordItemResult>​

    Creates or updates a webhook in the given record using the given options.

    Returns a promise that resolves with an object that contains whether the operation succeeded.

    The first parameter is a string and is the name of the record.

    The second parameter is a WebhookRecord and is the webhook that should be created or updated.

    The third parameter is optional and is a RecordActionOptions and is the options that should be used.

    Examples
    Create a publically-runnable webhook that runs from an inst.
    await os.recordWebhook('myRecord', {
      address: 'webhookAddress',
      targetResourceKind: 'inst',
      targetRecordName: 'myRecord',
      targetAddress: 'myInst',
      markers: ['publicRead']
    });
    Create a private webhook that runs from a data record.
    await os.recordWebhook('myRecord', {
      address: 'webhookAddress',
      targetResourceKind: 'data',
      targetRecordName: 'myRecord',
      targetAddress: 'myDataAddress',
    });
    Create a private webhook that runs from a file record.
    await os.recordWebhook('myRecord', {
      address: 'webhookAddress',
      targetResourceKind: 'file',
      targetRecordName: 'myRecord',
      targetAddress: 'myFileName',
    });

  • os.runWebhook(recordName: string, address: string, input: any, options?: RecordActionOptions): Promise<HandleWebhookResult>​

    Runs the webhook in the given record with the provided input.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address of the webhook.

    The third parameter is a any and is the input to provide to the webhook.

    The fourth parameter is optional and is a RecordActionOptions and is the options to use.

    Examples
    Run a webhook with some input.
    const result = await os.runWebhook('myRecord', 'myWebhookAddress', { myInput: 'myValue' });

  • os.eraseNotification(recordName: string, address: string, options?: RecordActionOptions): Promise<CrudEraseItemResult>​

    Deletes the notification from the given record.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address of the notification.

    The third parameter is optional and is a RecordActionOptions and is the options to use.

  • os.getWebhook(recordName: string, address: string, options?: RecordActionOptions): Promise<CrudGetItemResult>​

    Gets the notification from the given record.

    Returns a promise that resolves with the notification data.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address of the notification.

    The third parameter is optional and is a RecordActionOptions and is the options to use.

  • os.listNotificationSubscriptions(recordName: string, address: string, options?: RecordActionOptions): Promise<ListSubscriptionsResult>​

    Gets the list of subscriptions for the given notification in the given record.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address of the notification.

    The third parameter is optional and is a RecordActionOptions and is the options to use.

    Examples
    List notification subscriptions.
    const result = await os.listNotificationSubscriptions('myRecord', 'myNotificationAddress');

  • os.listNotifications(recordName: string, startingAddress: string, options?: ListNotificationsOptions): Promise<CrudListItemsResult>​

    Lists the notifications that are in the given record.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address after which items will be included in the list. Since items are ordered within the record by address, this can be used as way to iterate through all the webhooks items in a record. If omitted, then the list will start with the first item.

    The third parameter is optional and is a ListNotificationsOptions and is the options to use.

  • os.listNotificationsByMarker(recordName: string, marker: string, startingAddress: string, options?: ListNotificationsOptions): Promise<CrudListItemsResult>​

    Lists the webhooks that are in the given record.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the marker that needs to be assigned to the data items that should be included in the list. e.g. Using "publicRead" will return all data items with the "publicRead" marker.

    The third parameter is a string and is the address after which items will be included in the list. Since items are ordered within the record by address, this can be used as way to iterate through all the webhooks items in a record. If omitted, then the list will start with the first item.

    The fourth parameter is optional and is a ListNotificationsOptions and is the options to use.

  • os.listUserNotificationSubscriptions(options?: RecordActionOptions): Promise<ListSubscriptionsResult>​

    Gets the list of notification subscriptions for the current user.

    The first parameter is optional and is a RecordActionOptions and is the options to use.

    Examples
    List the current user's notification subscriptions.
    const result = await os.listUserNotificationSubscriptions();

  • os.recordNotification(recordName: string, notification: NotificationRecord, options?: RecordActionOptions): Promise<CrudRecordItemResult>​

    Creates or updates a notification in the given record using the given options.

    Returns a promise that resolves with an object that contains whether the operation succeeded.

    The first parameter is a string and is the name of the record.

    The second parameter is a NotificationRecord and is the notification that should be created or updated.

    The third parameter is optional and is a RecordActionOptions and is the options that should be used.

    Examples
    Create a notification that anyone can subscribe to.
    await os.recordNotification('myRecord', {
      address: 'notificationAddress',
      description: 'my notification',
      markers: ['publicRead']
    });
    Create a private notification.
    await os.recordNotification('myRecord', {
      address: 'notificationAddress',
      description: 'my notification',
      markers: ['private']
    });

  • os.sendNotification(recordName: string, address: string, payload: object, options?: SendNotificationOptions): Promise<SendNotificationResult>​

    Sends a notification to all subscribers of the given notification in the given record.

    Returns a promise that resolves with the result of the operation.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address of the notification.

    The third parameter is a object and is the payload to send.

    The fourth parameter is optional and is a SendNotificationOptions and is the options to use.

    Examples
    Send a notification.
    await os.sendNotification('myRecord', 'myNotificationAddress', {
        title: 'Hello',
        body: 'This is your first notification!',
    });

  • os.subscribeToNotification(recordName: string, address: string, options?: RecordActionOptions): Promise<SubscribeToNotificationResult>​

    Subscribes to the given notification in the given record.

    Returns a promise that resolves when the operation is complete.

    The first parameter is a string and is the name of the record.

    The second parameter is a string and is the address of the notification that should be subscribed to.

    The third parameter is optional and is a RecordActionOptions and is the options to use.

    Examples
    Subscribe to a notification.
    await os.subscribeToNotification('myRecord', 'myNotificationAddress');

  • os.unsubscribeFromNotification(subscriptionId: string, options?: RecordActionOptions): Promise<UnsubscribeToNotificationResult>​

    Unsubscribes from the given notification subscription.

    Returns a promise that resolves when the operation is complete.

    The first parameter is a string and is the ID of the subscription.

    The second parameter is optional and is a RecordActionOptions and is the options to use.

  • os.getRecordsEndpoint(): Promise<string>​

    Gets the default records endpoint. That is, the records endpoint that is used for records actions when no endpoint is specified.

    Examples
    Get the default records endpoint.
    const endpoint = await os.getRecordsEndpoint();
    os.toast("The default records endpoint is: " + endpoint);