Walkthrough: a team app
This walkthrough follows a typical request from an operations lead: "An app where my team submits purchase requests and I approve them, with a Teams message when one comes in." It is based on the expense-tracker example and touches most of the platform: a database with row-level security, app roles, storage and an integration.
What you'll build
- A Node app where people submit purchase requests with a receipt.
- Requesters see only their own requests; approvers see and decide all of them.
- Approvers get a Teams message for each new request.
- Receipts are stored in a private bucket that approvers can read.
1. Describe the data in a migration
Put SQL migrations in db/migrations/. They are applied in name order on deploy, each exactly once.
create table purchase_requests (
id bigint generated by default as identity primary key,
title text not null,
amount numeric(12,2) not null check (amount > 0),
status text not null default 'pending' check (status in ('pending','approved','rejected')),
created_by text not null default tc.user_id(),
created_by_name text default tc.user_name(),
created_at timestamptz not null default now()
);
alter table purchase_requests enable row level security;
create policy "own rows" on purchase_requests for all to tc_user
using (created_by = tc.user_id()) with check (created_by = tc.user_id());
create policy "approvers see and decide everything" on purchase_requests for all to tc_user
using (tc.has_role('approver')) with check (tc.has_role('approver'));
tc.user_id() and tc.has_role() read the signed-in person from the request, so a requester can't read someone else's row or insert a row "as" someone else. See Row-level security.
2. Declare the bucket and the integration
{
"integrations": { "teams": ["notify:role:approver", "notify:Finance - Accounting"] },
"storage": { "buckets": { "receipts": { "visibility": "private", "readRoles": ["approver"] } } },
"purpose": "Operations submits purchase requests (with a receipt) and approvers decide; approvers get a Teams message when one comes in."
}
3. Use the SDK
import { tc } from '@tenantcloud/sdk'
const me = await tc.auth.user()
const { data: requests } = await tc.db.from('purchase_requests')
.select('*').order('created_at', { ascending: false })
async function submit(title, amount, file) {
const { data: row, error } = await tc.db.from('purchase_requests')
.insert({ title, amount }).select().single()
if (error) return alert(error.message)
if (file) await tc.storage.from('receipts').upload(`${me.id}/${row.id}-${file.name}`, file)
}
import { tc } from '@tenantcloud/sdk'
await tc.teams.notify({ to: 'role:approver', text: `New purchase request: ${title} ($${amount})` })
Add "@tenantcloud/sdk": "*" to package.json. The builder vendors the SDK into the build; there's no registry to configure. Plain browser JavaScript with no bundler also needs an import map: the example serves the SDK's browser build from /vendor/tenantcloud/ and maps @tenantcloud/sdk (and @supabase/postgrest-js) to it in index.html. A Vite app needs neither.
4. Deploy
tc deploy ./expense-tracker -p expenses
The migration runs, the receipts bucket is created, and the deploy scan finds the tc.teams.notify call. Notifying people who can already open the app is auto-approved by a default policy; anything else becomes an access request.
5. Share it and assign roles
In the console open expenses › Access, choose Specific people and groups, add the Operations group, and under App roles give approver to the person who decides. Or from the API:
curl -X PUT https://console.apps.contoso.com/api/projects/expenses/access \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"mode":"groups","members":["Operations"],"roles":{"approver":["henrik.larsen@contoso.com"]}}'
6. Try it as different people
| Sign in as | What happens |
|---|---|
| A requester | Submits a request with a receipt; sees only their own requests |
| Another requester | Doesn't see the first person's requests; opening their receipt answers STORAGE_FORBIDDEN |
| The approver | Sees every request with its receipt and gets a Teams message for each new one |
| The owner, in the console | Database shows the table, its policies in plain English and the rows; Storage shows the receipts |