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
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
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.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
const result = await os.getData('myRecord', 'myAddress');
if (result.success) {
os.toast(result.data);
} else {
os.toast("Failed " + result.errorMessage);
}
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.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
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.
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.
os.grantRecordMarkerPermission(recordName: string, marker: string, permission: AvailablePermissions, options?: RecordActionOptions): Promise<GrantMarkerPermissionResult>
Grants the given marker 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 string and is the marker that the permission should be added to.
The third parameter is a AvailablePermissions and is the permission that should be added.
The fourth parameter is optional and is a RecordActionOptions and is the options for the operation.
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.
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
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
const result = await os.listData('myRecord');
if (result.success) {
os.toast(result.items);
} else {
os.toast("Failed " + result.errorMessage);
}
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.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
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);
}
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
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
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);
}
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);
}
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);
}
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.
Examples
await os.requestAuthBot();
os.toast("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.
os.revokeRecordMarkerPermission(recordName: string, marker: string, permission: AvailablePermissions, options?: RecordActionOptions): Promise<RevokeMarkerPermissionResult>
Revokes the given permission from the given marker 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 name of the marker that the permission should be removed from.
The third parameter is a AvailablePermissions and is the permission that should be removed.
The fourth 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.
