Skip to main content

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.

db/migrations/001_purchase_requests.sql
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​

tc.json
{
"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​

public/app.js (browser)
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)
}
server.js (Node)
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 asWhat happens
A requesterSubmits a request with a receipt; sees only their own requests
Another requesterDoesn't see the first person's requests; opening their receipt answers STORAGE_FORBIDDEN
The approverSees every request with its receipt and gets a Teams message for each new one
The owner, in the consoleDatabase shows the table, its policies in plain English and the rows; Storage shows the receipts

Where to go next​

Was this page helpful?