konnosDashboard
ProjectAPIDocs.constants.ts1266 lines · main
1import { DOCS_URL } from '@/lib/constants'
2
3export const API_DOCS_CATEGORIES = {
4 INTRODUCTION: 'introduction',
5 USER_MANAGEMENT: 'user-management',
6 ENTITIES: 'entities',
7 STORED_PROCEDURES: 'stored-procedures',
8 STORAGE: 'storage',
9 EDGE_FUNCTIONS: 'edge-functions',
10 REALTIME: 'realtime',
11}
12
13export const DOCS_MENU = [
14 { name: 'Connect', key: API_DOCS_CATEGORIES.INTRODUCTION },
15 { name: 'User Management', key: API_DOCS_CATEGORIES.USER_MANAGEMENT },
16 { name: 'Tables & Views', key: API_DOCS_CATEGORIES.ENTITIES },
17 { name: 'Database Functions', key: API_DOCS_CATEGORIES.STORED_PROCEDURES },
18 { name: 'Storage', key: API_DOCS_CATEGORIES.STORAGE },
19 { name: 'Edge Functions', key: API_DOCS_CATEGORIES.EDGE_FUNCTIONS },
20 { name: 'Realtime', key: API_DOCS_CATEGORIES.REALTIME },
21] as const
22
23export const DOCS_CONTENT = {
24 init: {
25 key: 'introduction',
26 category: API_DOCS_CATEGORIES.INTRODUCTION,
27 title: `Connect to your project`,
28 description: `Projects have a RESTful endpoint that you can use with your project's API key to query and manage your database. Put these keys in your .env file.`,
29 js: (_apikey?: string, endpoint?: string) => `
30import { createClient } from '@supabase/supabase-js'
31
32const brivenUrl = '${endpoint}'
33const brivenKey = process.env.BRIVEN_KEY
34const briven = createClient(brivenUrl, brivenKey)`,
35 bash: () => `# No client library required for Bash.`,
36 },
37 clientApiKeys: {
38 key: 'client-api-keys',
39 category: API_DOCS_CATEGORIES.INTRODUCTION,
40 title: `Client API Keys`,
41 description: `Client keys allow "anonymous access" to your database, until the user has logged in. After logging in, the keys will switch to the user's own login token.
42
43In this documentation, we will refer to the key using the name \`BRIVEN_KEY\`. You can find the \`anon\` key in the [API settings](/project/[ref]/settings/api) page.`,
44 js: (apikey?: string, endpoint?: string) => `
45const BRIVEN_KEY = '${apikey}'
46const BRIVEN_URL = '${endpoint}'
47const briven = createClient(BRIVEN_URL, process.env.BRIVEN_KEY);`,
48 bash: (apikey?: string, _endpoint?: string) => `${apikey}`,
49 },
50 serviceApiKeys: {
51 key: 'service-keys',
52 category: API_DOCS_CATEGORIES.INTRODUCTION,
53 title: `Service Keys`,
54 description: `Service keys have *FULL* access to your data, bypassing any security policies. Be VERY careful where you expose these keys. They should only be used on a server and never on a client or browser.
55
56In this documentation, we refer to the key using the name \`SERVICE_KEY\`. You can find the \`service_role\` key above or in the [API settings](/project/[ref]/settings/api) page.`,
57 js: (apikey?: string, endpoint?: string) => `
58const BRIVEN_KEY = '${apikey}'
59const BRIVEN_URL = 'https://${endpoint}'
60const briven = createClient(BRIVEN_URL, process.env.BRIVEN_KEY);`,
61 bash: (apikey?: string, _endpoint?: string) => `${apikey}`,
62 },
63 // User Management
64 userManagement: {
65 key: 'user-management',
66 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
67 title: `Introduction`,
68 description: `Briven makes it easy to manage your users.
69
70 Briven assigns each user a unique ID. You can reference this ID anywhere in your database. For example, you might create a \`profiles\` table references the user using a \`user_id\` field.
71
72 Briven already has built in the routes to sign up, login, and log out for managing users in your apps and websites.`,
73 js: undefined,
74 bash: undefined,
75 },
76 signUp: {
77 key: 'sign-up',
78 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
79 title: `Sign up`,
80 description: `Allow your users to sign up and create a new account
81
82 After they have signed up, all interactions using the Briven client will be performed as "that user".`,
83 js: (_apikey?: string, _endpoint?: string) => `
84const { data, error } = await briven.auth.signUp({
85 email: 'someone@email.com',
86 password: 'some-secure-password'
87})`,
88 bash: (apikey?: string, endpoint?: string) => `
89curl -X POST '${endpoint}/auth/v1/signup' \\
90-H "apikey: ${apikey}" \\
91-H "Content-Type: application/json" \\
92-d '{
93 "email": "someone@email.com",
94 "password": "some-secure-password"
95}'`,
96 },
97 emailLogin: {
98 key: 'email-login',
99 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
100 title: `Log in with Email/Password`,
101 description: `
102If an account is created, users can login to your app.
103
104After they have logged in, all interactions using the Briven JS client will be performed as "that user".`,
105 js: (_apikey?: string, _endpoint?: string) => `
106const { data, error } = await briven.auth.signInWithPassword({
107 email: 'someone@email.com',
108 password: 'some-secure-password'
109})
110 `,
111 bash: (apikey?: string, endpoint?: string) => `
112curl -X POST '${endpoint}/auth/v1/token?grant_type=password' \\
113-H "apikey: ${apikey}" \\
114-H "Content-Type: application/json" \\
115-d '{
116 "email": "someone@email.com",
117 "password": "some-secure-password"
118}'
119 `,
120 },
121 magicLinkLogin: {
122 key: 'magic-link-login',
123 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
124 title: `Log in with Magic Link via Email`,
125 description: `
126Send a user a passwordless link which they can use to redeem an access_token.
127
128After they have clicked the link, all interactions using the Briven JS client will be performed as "that user".`,
129 js: (_apikey?: string, _endpoint?: string) => `
130const { data, error } = await briven.auth.signInWithOtp({
131 email: 'someone@email.com'
132})
133 `,
134 bash: (apikey?: string, endpoint?: string) => `
135curl -X POST '${endpoint}/auth/v1/magiclink' \\
136-H "apikey: ${apikey}" \\
137-H "Content-Type: application/json" \\
138-d '{
139 "email": "someone@email.com"
140}'
141 `,
142 },
143 phoneLogin: {
144 key: 'phone-log-in',
145 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
146 title: `Sign up with Phone/Password`,
147 description: `
148A phone number can be used instead of an email as a primary account confirmation mechanism.
149
150The user will receive a mobile OTP via sms with which they can verify that they control the phone number.
151
152You must enter your own twilio credentials on the auth settings page to enable sms confirmations.`,
153 js: (_apikey?: string, _endpoint?: string) => `
154const { data, error } = await briven.auth.signUp({
155 phone: '+13334445555',
156 password: 'some-password'
157})
158 `,
159 bash: (apikey?: string, endpoint?: string) => `
160curl -X POST '${endpoint}/auth/v1/signup' \\
161-H "apikey: ${apikey}" \\
162-H "Content-Type: application/json" \\
163-d '{
164 "phone": "+13334445555",
165 "password": "some-password"
166}'
167 `,
168 },
169 smsLogin: {
170 key: 'sms-otp-log-in',
171 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
172 title: `Login via SMS OTP`,
173 description: `
174SMS OTPs work like magic links, except you have to provide an interface for the user to verify the 6 digit number they receive.
175
176You must enter your own twilio credentials on the auth settings page to enable SMS-based Logins.`,
177 js: (_apikey?: string, _endpoint?: string) => `
178const { data, error } = await briven.auth.signInWithOtp({
179 phone: '+13334445555'
180})
181 `,
182 bash: (apikey?: string, endpoint?: string) => `
183curl -X POST '${endpoint}/auth/v1/otp' \\
184-H "apikey: ${apikey}" \\
185-H "Content-Type: application/json" \\
186-d '{
187 "phone": "+13334445555"
188}'
189 `,
190 },
191 smsVerify: {
192 key: 'sms-verify',
193 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
194 title: `Verify an SMS OTP`,
195 description: `
196Once the user has received the OTP, have them enter it in a form and send it for verification
197
198You must enter your own twilio credentials on the auth settings page to enable SMS-based OTP verification.`,
199 js: (_apikey?: string, _endpoint?: string) => `
200const { data, error } = await briven.auth.verifyOtp({
201 phone: '+13334445555',
202 token: '123456',
203 type: 'sms'
204})
205 `,
206 bash: (apikey?: string, endpoint?: string) => `
207curl -X POST '${endpoint}/auth/v1/verify' \\
208-H "apikey: ${apikey}" \\
209-H "Content-Type: application/json" \\
210-d '{
211 "type": "sms",
212 "phone": "+13334445555",
213 "token": "123456"
214}'
215 `,
216 },
217 oauthLogin: {
218 key: 'oauth-login',
219 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
220 title: `Log in with Third Party OAuth`,
221 description: `
222Users can log in with Third Party OAuth like Google, Facebook, GitHub, and more. You must first enable each of these in the Auth Providers settings [here](https://supabase.com).
223
224View all the available [Third Party OAuth providers](https://supabase.com).
225
226After they have logged in, all interactions using the Briven JS client will be performed as "that user".
227
228Generate your Client ID and secret from: [Google](https://console.developers.google.com/apis/credentials), [Github](https://github.com/settings/applications/new), [Gitlab](https://gitlab.com/oauth/applications), [Facebook](https://developers.facebook.com/apps), and [Bitbucket](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud).`,
229 js: (_apikey?: string, _endpoint?: string) => `
230const { data, error } = await briven.auth.signInWithOAuth({
231 provider: 'github'
232})
233 `,
234 bash: (_apikey?: string, _endpoint?: string) => `No available command`,
235 },
236 user: {
237 key: 'get-user',
238 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
239 title: `Get user`,
240 description: `Get the JSON object for the logged in user.`,
241 js: (_apikey?: string, _endpoint?: string) => `
242const { data: { user } } = await briven.auth.getUser()
243 `,
244 bash: (apikey?: string, endpoint?: string) => `
245curl -X GET '${endpoint}/auth/v1/user' \\
246-H "apikey: ${apikey}" \\
247-H "Authorization: Bearer USER_TOKEN"
248 `,
249 },
250 forgotPassWordEmail: {
251 key: 'forgot-password-email',
252 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
253 title: `Forgot password / email`,
254 description: `Sends the user a log in link via email. Once logged in you should direct the user to a new password form. And use "Update User" below to save the new password.`,
255 js: (_apikey?: string, _endpoint?: string) => `
256const { data, error } = await briven.auth.resetPasswordForEmail(email)
257 `,
258 bash: (apikey?: string, endpoint?: string) => `
259curl -X POST '${endpoint}/auth/v1/recover' \\
260-H "apikey: ${apikey}" \\
261-H "Content-Type: application/json" \\
262-d '{
263"email": "someone@email.com"
264}'
265`,
266 },
267 updateUser: {
268 key: 'update-user',
269 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
270 title: `Update User`,
271 description: `Update the user with a new email or password. Each key (email, password, and data) is optional.`,
272 js: (_apikey?: string, _endpoint?: string) => `
273const { data, error } = await briven.auth.updateUser({
274 email: "new@email.com",
275 password: "new-password",
276 data: { hello: 'world' }
277})
278 `,
279 bash: (apikey?: string, endpoint?: string) => `
280curl -X PUT '${endpoint}/auth/v1/user' \\
281-H "apikey: ${apikey}" \\
282-H "Authorization: Bearer <USERS-ACCESS-TOKEN>" \\
283-H "Content-Type: application/json" \\
284-d '{
285"email": "someone@email.com",
286"password": "new-password",
287"data": {
288 "key": "value"
289}
290}'
291`,
292 },
293 logout: {
294 key: 'log-out',
295 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
296 title: `Log out`,
297 description: `After calling log out, all interactions using the Briven JS client will be "anonymous".`,
298 js: (_apikey?: string, _endpoint?: string) => `
299const { error } = await briven.auth.signOut()
300 `,
301 bash: (apikey?: string, endpoint?: string) => `
302curl -X POST '${endpoint}/auth/v1/logout' \\
303-H "apikey: ${apikey}" \\
304-H "Content-Type: application/json" \\
305-H "Authorization: Bearer USER_TOKEN"
306 `,
307 },
308 emailInvite: {
309 key: 'email-invite',
310 category: API_DOCS_CATEGORIES.USER_MANAGEMENT,
311 title: `Invite user over email`,
312 description: `
313Send a user a passwordless link which they can use to sign up and log in.
314
315After they have clicked the link, all interactions using the Briven JS client will be performed as "that user".
316
317This endpoint requires you use the \`service_role_key\` when initializing the client, and should only be invoked from the server, never from the client.`,
318 js: (_apikey?: string, _endpoint?: string) => `
319const { data, error } = await briven.auth.api.inviteUserByEmail('someone@email.com')
320 `,
321 bash: (apikey?: string, endpoint?: string) => `
322curl -X POST '${endpoint}/auth/v1/invite' \\
323-H "apikey: ${apikey}" \\
324-H "Authorization: Bearer ${apikey}" \\
325-H "Content-Type: application/json" \\
326-d '{
327 "email": "someone@email.com"
328}'
329 `,
330 },
331 // Storage
332 storage: {
333 key: 'storage',
334 category: API_DOCS_CATEGORIES.STORAGE,
335 title: `Introduction`,
336 description: `Briven Storage makes it simple to upload and serve files of any size, providing a robust framework for file access controls.
337
338You can use Briven Storage to store images, videos, documents, and any other file type. Serve your assets with a global CDN to reduce latency from over 285 cities globally. Briven Storage includes a built-in image optimizer, so you can resize and compress your media files on the fly.`,
339 js: undefined,
340 bash: undefined,
341 },
342 // Edge functions
343 edgeFunctions: {
344 key: 'edge-function',
345 category: API_DOCS_CATEGORIES.EDGE_FUNCTIONS,
346 title: 'Introduction',
347 description: `
348Edge Functions are server-side TypeScript functions, distributed globally at the edge—close to your users. They can be used for listening to webhooks or integrating your Briven project with third-parties like Stripe. Edge Functions are developed using Deno, which offers a few benefits to you as a developer:
349`,
350 js: undefined,
351 bash: undefined,
352 },
353 edgeFunctionsPreReq: {
354 key: 'edge-function-pre-req',
355 category: API_DOCS_CATEGORIES.EDGE_FUNCTIONS,
356 title: 'Pre-requisites',
357 description: `
358Follow the steps to prepare your Briven project on your local machine.
359
360- Install the Briven [CLI](${DOCS_URL}/guides/cli).
361- [Login to the CLI](${DOCS_URL}/reference/cli/usage#briven-login) using the command: \`briven login\`..
362- [Initialize Briven](${DOCS_URL}/guides/getting-started/local-development#getting-started) inside your project using the command: \`briven init\`..
363- [Link to your Remote Project](${DOCS_URL}/reference/cli/usage#briven-link) using the command \`briven link --project-ref [ref]\`..
364- Setup your environment: Follow the steps [here](${DOCS_URL}/guides/functions/quickstart#setting-up-your-environment).
365`,
366 js: undefined,
367 bash: undefined,
368 },
369 createEdgeFunction: {
370 key: 'create-edge-function',
371 category: API_DOCS_CATEGORIES.EDGE_FUNCTIONS,
372 title: 'Create an Edge Function',
373 description: `
374Create a Briven Edge Function locally via the Briven CLI.
375`,
376 js: () => `// Create an edge function via the Briven CLI`,
377 bash: () => `
378briven functions new hello-world
379`,
380 },
381 deployEdgeFunction: {
382 key: 'deploy-edge-function',
383 category: API_DOCS_CATEGORIES.EDGE_FUNCTIONS,
384 title: 'Deploy an Edge Function',
385 description: `
386Deploy a Briven Edge Function to your Briven project via the Briven CLI.
387`,
388 js: () => `// Deploy an edge function via the Briven CLI`,
389 bash: () => `briven functions deploy hello-world --project-ref [ref]
390`,
391 },
392 // Entities
393 entitiesIntroduction: {
394 key: 'entities-introduction',
395 category: API_DOCS_CATEGORIES.ENTITIES,
396 title: 'Introduction',
397 description: `
398All views and tables in the \`public\` schema, and those accessible by the active database role for a request are available for querying via the API.
399
400If you don't want to expose tables in your API, simply add them to a different schema (not the \`public\` schema).
401`,
402 js: undefined,
403 bash: undefined,
404 },
405 generatingTypes: {
406 key: 'generating-types',
407 category: API_DOCS_CATEGORIES.ENTITIES,
408 title: 'Generating Types',
409 description: `
410Briven APIs are generated from your database, which means that we can use database introspection to generate type-safe API definitions.
411
412You can generate types from your database either through the [Briven CLI](${DOCS_URL}/guides/database/api/generating-types), or by downloading the types file via the button on the right and importing it in your application within \`src/index.ts\`.
413`,
414 js: undefined,
415 bash: undefined,
416 },
417 graphql: {
418 key: 'graphql',
419 category: API_DOCS_CATEGORIES.ENTITIES,
420 title: 'GraphQL vs PostgREST',
421 description: `
422If you have a GraphQL background, you might be wondering if you can fetch your data in a single round-trip. The answer is yes! The syntax is very similar. This example shows how you might achieve the same thing with Apollo GraphQL and Briven.
423
424Still want GraphQL?
425If you still want to use GraphQL, you can. Briven provides you with a full Postgres database, so as long as your middleware can connect to the database then you can still use the tools you love. You can find the database connection details [in the settings](/project/[ref]/database/settings).
426`,
427 js: (_apikey?: string, _endpoint?: string) => `
428// With Apollo GraphQL
429const { loading, error, data } = useQuery(gql\`
430 query GetDogs {
431 dogs {
432 id
433 breed
434 owner {
435 id
436 name
437 }
438 }
439 }
440 \`)
441
442// With Briven
443const { data, error } = await briven
444 .from('dogs')
445 .select(\`
446 id, breed,
447 owner (id, name)
448 \`)
449`,
450 bash: (_apikey?: string, _endpoint?: string) => `
451// With Apollo GraphQL
452const { loading, error, data } = useQuery(gql\`
453 query GetDogs {
454 dogs {
455 id
456 breed
457 owner {
458 id
459 name
460 }
461 }
462 }
463 \`)
464
465// With Briven
466const { data, error } = await briven
467 .from('dogs')
468 .select(\`
469 id, breed,
470 owner (id, name)
471 \`)
472 `,
473 },
474 // Database Functions
475 storedProceduresIntroduction: {
476 key: 'stored-procedures-introduction',
477 category: API_DOCS_CATEGORIES.STORED_PROCEDURES,
478 title: 'Introduction',
479 description: `
480All of your database functions are available on your API. This means you can build your logic directly into the database (if you're brave enough)!
481
482The API endpoint supports POST (and in some cases GET) to execute the function.
483`,
484 js: undefined,
485 bash: undefined,
486 },
487 // Realtime
488 realtime: {
489 key: 'realtime-introduction',
490 category: API_DOCS_CATEGORIES.REALTIME,
491 title: 'Introduction',
492 description: `
493Briven provides a globally distributed cluster of Realtime servers that enable the following functionality:
494
495- [Broadcast](${DOCS_URL}/guides/realtime/broadcast): Send ephemeral messages from client to clients with low latency.
496- [Presence](${DOCS_URL}/guides/realtime/presence): Track and synchronize shared state between clients.
497- [Postgres Changes](${DOCS_URL}/guides/realtime/postgres-changes): Listen to Postgres database changes and send them to authorized clients.
498`,
499 js: undefined,
500 bash: undefined,
501 },
502 subscribeChannel: {
503 key: 'subscribe-to-channel',
504 category: API_DOCS_CATEGORIES.REALTIME,
505 title: 'Subscribe to channel',
506 description: `
507Creates an event handler that listens to changes.
508
509- By default, Broadcast and Presence are enabled for all projects.
510- By default, listening to database changes is disabled for new projects due to database performance and security concerns. You can turn it on by managing Realtime's [replication](${DOCS_URL}/guides/api#realtime-api-overview).
511- You can receive the "previous" data for updates and deletes by setting the table's \`REPLICA IDENTITY\` to \`FULL\` (e.g., \`ALTER TABLE your_table REPLICA IDENTITY FULL;\`).
512- Row level security is not applied to delete statements. When RLS is enabled and replica identity is set to full, only the primary key is sent to clients.
513`,
514 js: () => `
515briven
516 .channel('any')
517 .on('broadcast', { event: 'cursor-pos' }, payload => {
518 console.log('Cursor position received!', payload)
519 })
520 .subscribe((status) => {
521 if (status === 'SUBSCRIBED') {
522 channel.send({
523 type: 'broadcast',
524 event: 'cursor-pos',
525 payload: { x: Math.random(), y: Math.random() },
526 })
527 }
528 })
529 `,
530 bash: () => `# Realtime streams are only supported by our client libraries`,
531 },
532 unsubscribeChannel: {
533 key: 'unsubscribe-channel',
534 category: API_DOCS_CATEGORIES.REALTIME,
535 title: 'Unsubscribe from a channel',
536 description: `
537Unsubscribes and removes Realtime channel from Realtime client.
538
539Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Briven will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
540`,
541 js: () => `briven.removeChannel(myChannel)`,
542 bash: () => `# Realtime streams are only supported by our client libraries`,
543 },
544 unsubscribeChannels: {
545 key: 'unsubscribe-channels',
546 category: API_DOCS_CATEGORIES.REALTIME,
547 title: 'Unsubscribe from all channels',
548 description: `
549Unsubscribes and removes all Realtime channels from Realtime client.
550
551Removing a channel is a great way to maintain the performance of your project's Realtime service as well as your database if you're listening to Postgres changes. Briven will automatically handle cleanup 30 seconds after a client is disconnected, but unused channels may cause degradation as more clients are simultaneously subscribed.
552`,
553 js: () => `briven.removeChannels()`,
554 bash: () => `# Realtime streams are only supported by our client libraries`,
555 },
556 retrieveAllChannels: {
557 key: 'unsubscribe-channel',
558 category: API_DOCS_CATEGORIES.REALTIME,
559 title: 'Unsubscribe from a channel',
560 description: `
561Returns all Realtime channels.
562`,
563 js: () => `const channels = briven.getChannels()`,
564 bash: () => `# Realtime streams are only supported by our client libraries`,
565 },
566}
567
568export const DOCS_RESOURCE_CONTENT: {
569 [key: string]: {
570 key: string
571 title: string
572 category: string
573 description?: string
574 docsUrl: string
575 code: (props: any) => { key: string; title?: string; bash: string; js: string }[]
576 }
577} = {
578 rpcSingle: {
579 key: 'invoke-function',
580 title: 'Invoke function',
581 category: API_DOCS_CATEGORIES.STORED_PROCEDURES,
582 description: undefined,
583 docsUrl: `${DOCS_URL}/reference/javascript/rpc`,
584 code: ({
585 rpcName,
586 rpcParams,
587 endpoint,
588 apiKey,
589 showBearer = true,
590 }: {
591 rpcName: string
592 rpcParams: any[]
593 endpoint: string
594 apiKey: string
595 showBearer: boolean
596 }) => {
597 let rpcList = rpcParams.map((x) => `"${x.name}": "value"`).join(', ')
598 let noParams = !rpcParams.length
599 let bashParams = noParams ? '' : `\n-d '{ ${rpcList} }' \\`
600 let jsParams = noParams
601 ? ''
602 : `, {${
603 rpcParams.length
604 ? rpcParams
605 .map((x) => `\n ${x.name}`)
606 .join(`, `)
607 .concat('\n ')
608 : ''
609 }}`
610 return [
611 {
612 key: 'rpc-single',
613 title: undefined,
614 bash: `
615 curl -X POST '${endpoint}/rest/v1/rpc/${rpcName}' \\${bashParams}
616 -H "Content-Type: application/json" \\
617 -H "apikey: ${apiKey}" ${
618 showBearer
619 ? `\\
620 -H "Authorization: Bearer ${apiKey}"`
621 : ''
622 }
623 `,
624 js: `
625let { data, error } = await briven
626 .rpc('${rpcName}'${jsParams})
627
628if (error) console.error(error)
629else console.log(data)
630 `,
631 },
632 ]
633 },
634 },
635 readRows: {
636 key: 'read-rows',
637 title: `Read rows`,
638 category: API_DOCS_CATEGORIES.ENTITIES,
639 docsUrl: `${DOCS_URL}/reference/javascript/select`,
640 description: `To read rows in this table, use the \`select\` method.`,
641 code: ({
642 resourceId,
643 endpoint,
644 apikey,
645 }: {
646 resourceId: string
647 endpoint: string
648 apikey: string
649 }) => {
650 return [
651 {
652 key: 'read-all-rows',
653 title: 'Read all rows',
654 bash: `
655curl '${endpoint}/rest/v1/${resourceId}?select=*' \\
656-H "apikey: ${apikey}" \\
657-H "Authorization: Bearer ${apikey}"
658 `,
659 js: `
660let { data: ${resourceId}, error } = await briven
661 .from('${resourceId}')
662 .select('*')
663 `,
664 },
665 {
666 key: 'read-specific-columns',
667 title: 'Read specific columns',
668 bash: `
669curl '${endpoint}/rest/v1/${resourceId}?select=some_column,other_column' \\
670-H "apikey: ${apikey}" \\
671-H "Authorization: Bearer ${apikey}"
672 `,
673 js: `
674let { data: ${resourceId}, error } = await briven
675 .from('${resourceId}')
676 .select('some_column,other_column')
677 `,
678 },
679 {
680 key: 'read-foreign-tables',
681 title: 'Read referenced tables',
682 bash: `
683curl '${endpoint}/rest/v1/${resourceId}?select=some_column,other_table(foreign_key)' \\
684-H "apikey: ${apikey}" \\
685-H "Authorization: Bearer ${apikey}"
686 `,
687 js: `
688let { data: ${resourceId}, error } = await briven
689 .from('${resourceId}')
690 .select(\`
691 some_column,
692 other_table (
693 foreign_key
694 )
695 \`)
696 `,
697 },
698 {
699 key: 'with-pagination',
700 title: 'With pagination',
701 bash: `
702curl '${endpoint}/rest/v1/${resourceId}?select=*' \\
703-H "apikey: ${apikey}" \\
704-H "Authorization: Bearer ${apikey}" \\
705-H "Range: 0-9"
706 `,
707 js: `
708let { data: ${resourceId}, error } = await briven
709 .from('${resourceId}')
710 .select('*')
711 .range(0, 9)
712 `,
713 },
714 ]
715 },
716 },
717 filtering: {
718 key: 'filter-rows',
719 category: API_DOCS_CATEGORIES.ENTITIES,
720 title: 'Filtering',
721 description: `Briven provides a wide range of filters`,
722 docsUrl: `${DOCS_URL}/reference/javascript/using-filters`,
723 code: ({
724 resourceId,
725 endpoint,
726 apikey,
727 }: {
728 resourceId: string
729 endpoint: string
730 apikey: string
731 }) => {
732 return [
733 {
734 key: 'with-filtering',
735 title: 'With filtering',
736 bash: `
737curl --get '${endpoint}/rest/v1/${resourceId}' \\
738-H "apikey: ${apikey}" \\
739-H "Authorization: Bearer ${apikey}" \\
740-H "Range: 0-9" \\
741-d "select=*" \\
742\\
743\`# Filters\` \\
744-d "column=eq.Equal+to" \\
745-d "column=gt.Greater+than" \\
746-d "column=lt.Less+than" \\
747-d "column=gte.Greater+than+or+equal+to" \\
748-d "column=lte.Less+than+or+equal+to" \\
749-d "column=like.*CaseSensitive*" \\
750-d "column=ilike.*CaseInsensitive*" \\
751-d "column=is.null" \\
752-d "column=in.(Array,Values)" \\
753-d "column=neq.Not+equal+to" \\
754\\
755\`# Arrays\` \\
756-d "array_column=cs.{array,contains}" \\
757-d "array_column=cd.{contained,by}" \\
758\\
759\`# Logical operators\` \\
760-d "column=not.like.Negate+filter" \\
761-d "or=(some_column.eq.Some+value,other_column.eq.Other+value)"
762 `,
763 js: `
764let { data: ${resourceId}, error } = await briven
765 .from('${resourceId}')
766 .select("*")
767
768 // Filters
769 .eq('column', 'Equal to')
770 .gt('column', 'Greater than')
771 .lt('column', 'Less than')
772 .gte('column', 'Greater than or equal to')
773 .lte('column', 'Less than or equal to')
774 .like('column', '%CaseSensitive%')
775 .ilike('column', '%CaseInsensitive%')
776 .is('column', null)
777 .in('column', ['Array', 'Values'])
778 .neq('column', 'Not equal to')
779
780 // Arrays
781 .contains('array_column', ['array', 'contains'])
782 .containedBy('array_column', ['contained', 'by'])
783
784 // Logical operators
785 .not('column', 'like', 'Negate filter')
786 .or('some_column.eq.Some value, other_column.eq.Other value')
787 `,
788 },
789 ]
790 },
791 },
792 insertRows: {
793 key: 'insert-rows',
794 category: API_DOCS_CATEGORIES.ENTITIES,
795 title: 'Insert rows',
796 description: `
797\`insert\` lets you insert into your tables. You can also insert in bulk and do UPSERT.
798
799\`insert\` will also return the replaced values for UPSERT.
800`,
801 docsUrl: `${DOCS_URL}/reference/javascript/insert`,
802 code: ({
803 resourceId,
804 endpoint,
805 apikey,
806 }: {
807 resourceId: string
808 endpoint: string
809 apikey: string
810 }) => {
811 return [
812 {
813 key: 'insert-a-row',
814 title: 'Insert a row',
815 bash: `
816curl -X POST '${endpoint}/rest/v1/${resourceId}' \\
817-H "apikey: ${apikey}" \\
818-H "Authorization: Bearer ${apikey}" \\
819-H "Content-Type: application/json" \\
820-H "Prefer: return=minimal" \\
821-d '{ "some_column": "someValue", "other_column": "otherValue" }'
822 `,
823 js: `
824const { data, error } = await briven
825 .from('${resourceId}')
826 .insert([
827 { some_column: 'someValue', other_column: 'otherValue' },
828 ])
829 .select()
830 `,
831 },
832 {
833 key: 'insert-many-rows',
834 title: 'Insert many rows',
835 bash: `
836curl -X POST '${endpoint}/rest/v1/${resourceId}' \\
837-H "apikey: ${apikey}" \\
838-H "Authorization: Bearer ${apikey}" \\
839-H "Content-Type: application/json" \\
840-d '[{ "some_column": "someValue" }, { "other_column": "otherValue" }]'
841 `,
842 js: `
843const { data, error } = await briven
844 .from('${resourceId}')
845 .insert([
846 { some_column: 'someValue' },
847 { some_column: 'otherValue' },
848 ])
849 .select()
850 `,
851 },
852 {
853 key: 'upsert-matching-rows',
854 title: 'Upsert matching rows',
855 bash: `
856curl -X POST '${endpoint}/rest/v1/${resourceId}' \\
857-H "apikey: ${apikey}" \\
858-H "Authorization: Bearer ${apikey}" \\
859-H "Content-Type: application/json" \\
860-H "Prefer: resolution=merge-duplicates" \\
861-d '{ "some_column": "someValue", "other_column": "otherValue" }'
862 `,
863 js: `
864const { data, error } = await briven
865 .from('${resourceId}')
866 .upsert({ some_column: 'someValue' })
867 .select()
868 `,
869 },
870 ]
871 },
872 },
873 updateRows: {
874 key: 'update-rows',
875 category: API_DOCS_CATEGORIES.ENTITIES,
876 title: 'Update rows',
877 description: `
878\`update\` lets you update rows. \`update\` will match all rows by default. You can update specific rows using horizontal filters, e.g. \`eq\`, \`lt\`, and \`is\`.
879
880\`update\` will also return the replaced values for UPDATE.
881`,
882 docsUrl: `${DOCS_URL}/reference/javascript/update`,
883 code: ({
884 resourceId,
885 endpoint,
886 apikey,
887 }: {
888 resourceId: string
889 endpoint: string
890 apikey: string
891 }) => {
892 return [
893 {
894 key: 'update-matching-rows',
895 title: 'Update matching rows',
896 bash: `
897curl -X PATCH '${endpoint}/rest/v1/${resourceId}?some_column=eq.someValue' \\
898-H "apikey: ${apikey}" \\
899-H "Authorization: Bearer ${apikey}" \\
900-H "Content-Type: application/json" \\
901-H "Prefer: return=minimal" \\
902-d '{ "other_column": "otherValue" }'
903 `,
904 js: `
905const { data, error } = await briven
906 .from('${resourceId}')
907 .update({ other_column: 'otherValue' })
908 .eq('some_column', 'someValue')
909 .select()
910 `,
911 },
912 ]
913 },
914 },
915 deleteRows: {
916 key: 'delete-rows',
917 category: API_DOCS_CATEGORIES.ENTITIES,
918 title: 'Delete rows',
919 description: `
920\`delete\` lets you delete rows. \`delete\` will match all rows by default, so remember to specify your filters!
921`,
922 docsUrl: `${DOCS_URL}/reference/javascript/delete`,
923 code: ({
924 resourceId,
925 endpoint,
926 apikey,
927 }: {
928 resourceId: string
929 endpoint: string
930 apikey: string
931 }) => {
932 return [
933 {
934 key: 'delete-matching-rows',
935 title: 'Delete matching rows',
936 bash: `
937curl -X DELETE '${endpoint}/rest/v1/${resourceId}?some_column=eq.someValue' \\
938-H "apikey: ${apikey}" \\
939-H "Authorization: Bearer ${apikey}"
940 `,
941 js: `
942const { error } = await briven
943 .from('${resourceId}')
944 .delete()
945 .eq('some_column', 'someValue')
946 `,
947 },
948 ]
949 },
950 },
951 subscribeChanges: {
952 key: 'subscribe-changes',
953 category: API_DOCS_CATEGORIES.ENTITIES,
954 title: 'Subscribe to changes',
955 description: `
956Briven provides realtime functionality and broadcasts database changes to authorized users depending on Row Level Security (RLS) policies.
957`,
958 docsUrl: `${DOCS_URL}/reference/javascript/subscribe`,
959 code: ({ resourceId }: { resourceId: string }) => {
960 return [
961 {
962 key: 'subscribe-all-events',
963 title: 'Subscribe to all events',
964 bash: `# Realtime streams are only supported by our client libraries`,
965 js: `
966const channels = briven.channel('custom-all-channel')
967 .on(
968 'postgres_changes',
969 { event: '*', schema: 'public', table: '${resourceId}' },
970 (payload) => {
971 console.log('Change received!', payload)
972 }
973 )
974 .subscribe()`,
975 },
976 {
977 key: 'subscribe-to-inserts',
978 title: 'Subscribe to inserts',
979 bash: `# Realtime streams are only supported by our client libraries`,
980 js: `
981const channels = briven.channel('custom-insert-channel')
982 .on(
983 'postgres_changes',
984 { event: 'INSERT', schema: 'public', table: '${resourceId}' },
985 (payload) => {
986 console.log('Change received!', payload)
987 }
988 )
989 .subscribe()`,
990 },
991 {
992 key: 'subscribe-to-updates',
993 title: 'Subscribe to updates',
994 bash: `# Realtime streams are only supported by our client libraries`,
995 js: `
996const channels = briven.channel('custom-update-channel')
997 .on(
998 'postgres_changes',
999 { event: 'UPDATE', schema: 'public', table: '${resourceId}' },
1000 (payload) => {
1001 console.log('Change received!', payload)
1002 }
1003 )
1004 .subscribe()`,
1005 },
1006 {
1007 key: 'subscribe-to-deletes',
1008 title: 'Subscribe to deletes',
1009 bash: `# Realtime streams are only supported by our client libraries`,
1010 js: `
1011const channels = briven.channel('custom-delete-channel')
1012 .on(
1013 'postgres_changes',
1014 { event: 'DELETE', schema: 'public', table: '${resourceId}' },
1015 (payload) => {
1016 console.log('Change received!', payload)
1017 }
1018 )
1019 .subscribe()`,
1020 },
1021 {
1022 key: 'subscribe-to-specific-rows',
1023 title: 'Subscribe to specific rows',
1024 bash: `# Realtime streams are only supported by our client libraries`,
1025 js: `
1026const channels = briven.channel('custom-filter-channel')
1027 .on(
1028 'postgres_changes',
1029 { event: '*', schema: 'public', table: '${resourceId}', filter: 'some_column=eq.some_value' },
1030 (payload) => {
1031 console.log('Change received!', payload)
1032 }
1033 )
1034 .subscribe()`,
1035 },
1036 ]
1037 },
1038 },
1039 uploadFile: {
1040 key: 'upload-file',
1041 category: API_DOCS_CATEGORIES.STORAGE,
1042 title: 'Upload a file',
1043 docsUrl: `${DOCS_URL}/reference/javascript/storage-from-upload`,
1044 description: `
1045Upload a file to an existing bucket. RLS policy permissions required:
1046- \`buckets\` table permissions: none
1047- \`objects\` table permissions: only \`insert\` when you are uploading new files and \`select\`, \`insert\`, and \`update\` when you are upserting files.
1048`,
1049 code: ({ name, apikey, endpoint }: { name: string; apikey: string; endpoint: string }) => [
1050 {
1051 key: 'storage-upload-file',
1052 title: undefined,
1053 bash: `
1054curl -X POST '${endpoint}/storage/v1/object/${name}/folder/avatar1.png' \\
1055-H 'Content-Type: image/png' \\
1056-H "Authorization: Bearer ${apikey}" \\
1057--data-binary @/path/to/your/file'
1058-H 'Content-Type: multipart/form-data' \\
1059-H "Authorization: Bearer ${apikey}" \\
1060--data-raw $'your_file_data'
1061 `,
1062 js: `
1063const avatarFile = event.target.files[0]
1064const { data, error } = await briven
1065 .storage
1066 .from('${name}')
1067 .upload('folder/avatar1.png', avatarFile, {
1068 cacheControl: '3600',
1069 upsert: false
1070 })
1071`,
1072 },
1073 ],
1074 },
1075 deleteFiles: {
1076 key: 'delete-files',
1077 category: API_DOCS_CATEGORIES.STORAGE,
1078 title: 'Delete files',
1079 docsUrl: `${DOCS_URL}/reference/javascript/storage-from-remove`,
1080 description: `
1081Delete files within the bucket. RLS policy permissions required:
1082- \`buckets\` table permissions: none
1083- \`objects\` table permissions: \`delete\` and \`select\`
1084`,
1085 code: ({ name, apikey, endpoint }: { name: string; apikey: string; endpoint: string }) => [
1086 {
1087 key: 'storage-delete-files',
1088 title: undefined,
1089 bash: `
1090curl -X DELETE '${endpoint}/storage/v1/object/${name}' \\
1091-H "Content-Type: application/json" \\
1092-H "Authorization: Bearer ${apikey}" \\
1093-d '{ "prefixes": ["file_name", "another_file_name"] }'
1094`,
1095 js: `
1096const { data, error } = await briven
1097 .storage
1098 .from('${name}')
1099 .remove(['folder/avatar1.png'])
1100 `,
1101 },
1102 ],
1103 },
1104 listFiles: {
1105 key: 'list-files',
1106 category: API_DOCS_CATEGORIES.STORAGE,
1107 title: 'List all files',
1108 docsUrl: `${DOCS_URL}/reference/javascript/storage-from-list`,
1109 description: `
1110List all files within the bucket. RLS policy permissions required:
1111- \`buckets\` table permissions: none
1112- \`objects\` table permissions: \`select\`
1113`,
1114 code: ({ name, apikey, endpoint }: { name: string; apikey: string; endpoint: string }) => [
1115 {
1116 key: 'storage-list-files',
1117 title: undefined,
1118 bash: `
1119curl -X POST '${endpoint}/storage/v1/object/list/${name}' \\
1120-H "Content-Type: application/json" \\
1121-H "Authorization: Bearer ${apikey}" \\
1122-d '{ "limit": 100, "offset": 0, "prefix": "", "sortBy": { "column": "name", "order": "asc" } }'`,
1123 js: `
1124const { data, error } = await briven
1125 .storage
1126 .from('${name}')
1127 .list('folder', {
1128 limit: 100,
1129 offset: 0,
1130 sortBy: { column: 'name', order: 'asc' },
1131 })
1132 `,
1133 },
1134 ],
1135 },
1136 downloadFile: {
1137 key: 'download-file',
1138 category: API_DOCS_CATEGORIES.STORAGE,
1139 title: 'Download a file',
1140 docsUrl: `${DOCS_URL}/reference/javascript/storage-from-download`,
1141 description: `
1142Downloads a file from a private bucket. For public buckets, make a request to the URL returned from getPublicUrl instead. RLS policy permissions required:
1143- \`buckets\` table permissions: none
1144- \`objects\` table permissions: \`select\`
1145`,
1146 code: ({ name, apikey, endpoint }: { name: string; apikey: string; endpoint: string }) => [
1147 {
1148 key: 'storage-download-file',
1149 title: undefined,
1150 bash: `
1151curl -X GET '${endpoint}/storage/v1/object/${name}/folder/avatar1.png' \\
1152-H "Content-Type: application/json" \\
1153-H "Authorization: Bearer ${apikey}" \\
1154--output avatar1.png
1155`,
1156 js: `
1157const { data, error } = await briven
1158 .storage
1159 .from('${name}')
1160 .download('folder/avatar1.png')
1161 `,
1162 },
1163 ],
1164 },
1165 createSignedURL: {
1166 key: 'create-signed-url',
1167 category: API_DOCS_CATEGORIES.STORAGE,
1168 title: 'Create a signed URL',
1169 docsUrl: `${DOCS_URL}/reference/javascript/storage-from-createsignedurl`,
1170 description: `
1171Create a signed URL which can be used to share a file for a fixed amount of time. RLS policy permissions required:
1172- \`buckets\` table permissions: none
1173- \`objects\` table permissions: \`select\`
1174`,
1175 code: ({ name, apikey, endpoint }: { name: string; apikey: string; endpoint: string }) => [
1176 {
1177 key: 'storage-create-signed-url',
1178 title: undefined,
1179 bash: `
1180curl -X POST '${endpoint}/storage/v1/object/sign/${name}/folder/avatar1.png' \\
1181-H "Content-Type: application/json" \\
1182-H "Authorization: Bearer ${apikey}" \\
1183-d '{ "expiresIn": 60 }'
1184 `,
1185 js: `
1186const { data, error } = await briven
1187 .storage
1188 .from('${name}')
1189 .createSignedUrl('folder/avatar1.png', 60)
1190 `,
1191 },
1192 ],
1193 },
1194 retrievePublicURL: {
1195 key: 'retrieve-public-url',
1196 category: API_DOCS_CATEGORIES.STORAGE,
1197 title: 'Retrieve public URL',
1198 docsUrl: `${DOCS_URL}/reference/javascript/storage-from-getpublicurl`,
1199 description: `
1200A simple convenience function to get the URL for an asset in a public bucket. If you do not want to use this function, you can construct the public URL by concatenating the bucket URL with the path to the asset.
1201
1202This function does not verify if the bucket is public. If a public URL is created for a bucket which is not public, you will not be able to download the asset.
1203
1204The bucket needs to be set to public, either via \`updateBucket()\` or by going to Storage on supabase.com/dashboard, clicking the overflow menu on a bucket and choosing "Make public"
1205
1206RLS policy permissions required:
1207- \`buckets\` table permissions: none
1208- \`objects\` table permissions: none
1209`,
1210 code: ({
1211 name,
1212 apikey: _apikey,
1213 endpoint,
1214 }: {
1215 name: string
1216 apikey: string
1217 endpoint: string
1218 }) => [
1219 {
1220 key: 'storage-retrieve-public-url',
1221 title: undefined,
1222 bash: `
1223# No bash command available.
1224# You can construct the public URL by concatenating the bucket URL with the path to the asset
1225# e.g ${endpoint}/storage/v1/object/public/${name}/folder/avatar1.png`,
1226 js: `
1227const { data } = briven
1228 .storage
1229 .from('${name}')
1230 .getPublicUrl('folder/avatar1.png')
1231 `,
1232 },
1233 ],
1234 },
1235 invokeEdgeFunction: {
1236 key: 'invoke-edge-function',
1237 category: API_DOCS_CATEGORIES.EDGE_FUNCTIONS,
1238 title: 'Invoke an edge function',
1239 docsUrl: `${DOCS_URL}/reference/javascript/functions-invoke`,
1240 description: `
1241Invokes a Briven Edge Function. Requires an Authorization header, and invoke params generally match the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) spec.
1242
1243When you pass in a body to your function, we automatically attach the \`Content-Type\` header for \`Blob\`, \`ArrayBuffer\`, \`File\`, \`FormData\` and \`String\`. If it doesn't match any of these types we assume the payload is \`json\`, serialize it and attach the \`Content-Type\` header as \`application/json\`. You can override this behavior by passing in a \`Content-Type\` header of your own.
1244
1245Responses are automatically parsed as \`json\`, \`blob\` and \`form-data\` depending on the \`Content-Type\` header sent by your function. Responses are parsed as \`text\` by default.
1246`,
1247 code: ({ name, endpoint, apikey }: { name: string; endpoint: string; apikey: string }) => [
1248 {
1249 key: 'invoke-edge-function',
1250 title: undefined,
1251 bash: `
1252curl --request POST '${endpoint}/functions/v1/${name}' \\
1253--header 'Authorization: Bearer ${apikey}' \\
1254--header 'Content-Type: application/json' \\
1255--data '{ "name": "Functions" }'
1256 `,
1257 js: `
1258const { data, error } = await briven
1259 .functions
1260 .invoke('${name}', {
1261 body: { foo: 'bar' }
1262 })`,
1263 },
1264 ],
1265 },
1266} as const