Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
import type {
AccessLevel,
AccessRequest as RequestRecord,
ResolveRequest,
ShareEntityType,
} from '../../../generated/storage/types.gen';
import { MacroNotFoundError, unwrap } from '../../utils';
import type { MacroClient } from '../../utils/client';
import { MacroEntity } from '../entity';
import { User } from '../users/user';
/** Access requests and direct grants scoped to a shareable entity. */
export class EntityAccess {
constructor(
private readonly client: MacroClient,
private readonly entityType: ShareEntityType,
private readonly entity: { readonly id: string },
) {}
private get path() {
return { entity_type: this.entityType, entity_id: this.entity.id };
}
/** A page of access requests, including the caller's own request and review rights. */
async state(offset?: number) {
const state = unwrap(
await this.client.storage.accessRequestsState({
path: this.path,
query: { offset },
}),
);
return {
accessLevel: state.accessLevel ?? undefined,
canReview: state.canReview,
owner: state.owner ? User.byId(this.client, state.owner) : undefined,
pendingCount: state.pendingCount,
supportedLevels: state.supportedLevels,
nextOffset: state.nextOffset ?? undefined,
mine: state.mine
? AccessRequest.from(this.client, this, state.mine)
: undefined,
requests: state.requests.map((r) =>
AccessRequest.from(this.client, this, r),
),
};
}
/**
* Ask the item's reviewers for more access in the caller's name, as the Share
* menu's Request access does, superseding the caller's latest request.
*
* Agents: call this only when the user asked for it or agreed after being
* offered it, typically after a write failed with `MacroForbiddenError`
* because the user can only view the item; never request access on your
* own. It never grants access: the request stays pending until a reviewer
* decides. Tell the user it is pending and who reviews it (`state().owner`),
* do not claim the failed write succeeded, check `state()` later (`mine`
* holds this request's `status()`), and retry the write only once
* `state().accessLevel` allows it.
*/
async request(
requestedLevel: Exclude<AccessLevel, 'owner'>,
): Promise<AccessRequest> {
const { mine } = await this.state();
return this.submit(
requestedLevel,
mine ? await mine.revision() : undefined,
);
}
/** Request access, optionally naming the revision of an earlier request. */
async submit(
requestedLevel: AccessLevel,
revision?: number,
): Promise<AccessRequest> {
return AccessRequest.from(
this.client,
this,
unwrap(
await this.client.storage.accessRequestsSubmit({
path: this.path,
body: { requestedLevel, revision },
}),
),
);
}
/** Cancel the caller's own request at its observed revision. */
async cancel(revision: number): Promise<void> {
unwrap(
await this.client.storage.accessRequestsCancel({
path: this.path,
query: { revision },
}),
);
}
/** Direct grants expressed as user handles. */
async direct() {
return unwrap(
await this.client.storage.accessRequestsDirect({ path: this.path }),
).map((g) => ({
user: User.byId(this.client, g.userId),
accessLevel: g.accessLevel,
}));
}
/** Grant direct access, or remove it by omitting the access level. */
async grant(user: User, accessLevel?: AccessLevel): Promise<void> {
unwrap(
await this.client.storage.accessRequestsSetDirect({
path: { ...this.path, user_id: user.id },
body: { accessLevel },
}),
);
}
/** Remove one user's direct grant. */
async remove(user: User): Promise<void> {
unwrap(
await this.client.storage.accessRequestsRemoveDirect({
path: { ...this.path, user_id: user.id },
}),
);
}
/** Resolve a request belonging to this entity at an observed revision. */
async resolve(
request: AccessRequest,
resolution: ResolveRequest,
): Promise<RequestRecord> {
const owner = request.access.toJSON();
if (
owner.entity_type !== this.entityType ||
owner.entity_id !== this.entity.id
)
throw new Error('Access request belongs to another entity');
return unwrap(
await this.client.storage.accessRequestsResolve({
path: { ...this.path, request_id: request.id },
body: resolution,
}),
);
}
/** Serialize the entity reference without credentials. */
toJSON() {
return this.path;
}
}
/** One access request; resolutions preserve optimistic concurrency. */
export class AccessRequest extends MacroEntity<RequestRecord> {
private resolvedRecord?: RequestRecord;
private constructor(
client: MacroClient,
/** Entity access surface owning the request. */
readonly access: EntityAccess,
record: RequestRecord,
) {
super(client, record.id, record);
}
/** Seed a request from a state or submission response. */
static from(
client: MacroClient,
access: EntityAccess,
record: RequestRecord,
): AccessRequest {
return new AccessRequest(client, access, record);
}
protected async fetch(): Promise<RequestRecord> {
if (this.resolvedRecord) return this.resolvedRecord;
let offset: number | undefined;
do {
const state = await this.access.state(offset);
const found = [state.mine, ...state.requests].find(
(r) => r?.id === this.id,
);
if (found) return found.detail.get();
offset = state.nextOffset;
} while (offset !== undefined);
throw new MacroNotFoundError(`Access request ${this.id} is unavailable`);
}
/** Request revision. */
readonly revision = this.field('revision');
/** Current request state. */
readonly status = this.field('status');
/** Requested access. */
readonly requestedLevel = this.field('requestedLevel');
/** Requesting user. */
readonly requester = this.mappedField('requesterId', (id) =>
User.byId(this.client, id),
);
/** Approve with an access level, or decline by omitting it. */
async resolve(grantedLevel?: AccessLevel): Promise<void> {
this.resolvedRecord = await this.access.resolve(this, {
revision: await this.revision(),
grantedLevel,
});
this.detail.clear();
}
}