SDK Documentation Upgrade (v0.2.2 Parity)#92
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 24 minutes and 48 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
📝 WalkthroughWalkthroughUpdated SDK documentation: added Schema and Mail pages; refactored Auth to use Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (1)
mintlify/docs/sdk/auth.mdx (1)
109-176: Use sentence case and code formatting for method-name headings.Several headings (for example, “Social Auth”, “Account Verification”, “Manual Token Management”, and “logout”) are inconsistent with the docs style rules for headings and code references.
As per coding guidelinesUse sentence case for headings in documentationandUse code formatting for file names, commands, paths, and code references.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@mintlify/docs/sdk/auth.mdx` around lines 109 - 176, Change heading text to sentence case and wrap method-name headings in inline code formatting: update "Social Auth" to "Social auth", "Account Verification" to "Account verification", "Manual Token Management" to "Manual token management", and format method headings like socialStart, socialExchange, publicProfile, and logout as `socialStart`, `socialExchange`, `publicProfile`, and `logout`; ensure the examples and table entries use backticks for method names (e.g., `verifyEmail`, `resendVerificationOtp`, `requestPasswordReset`, `resetPassword`) so all code references follow the docs style rules.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@mintlify/docs/sdk/auth.mdx`:
- Around line 123-138: Update the docs: change the phrase "for a session" to
"for a refresh token" in the socialExchange description and update the example
to validate URL params before calling client.auth.socialExchange; specifically,
ensure token and rtCode (from URLSearchParams.get) are checked for
null/undefined and handle/report missing values (e.g., throw or return early) so
you only call socialExchange with required string values matching
SocialExchangePayload and return type SocialExchangeResponse.
- Around line 41-46: Update the AuthResponse interface in the docs to match the
SDK type contract by making all fields optional and including the missing userId
field; locate the AuthResponse declaration in this file and change accessToken,
token, user, expiresIn (and any nested fields if applicable in AuthUser) to
optional, and add userId?: string (or the correct type) so the documented
interface mirrors sdks/urbackend-sdk/src/types/index.ts.
In `@mintlify/docs/sdk/database.mdx`:
- Line 9: Update the documentation sentence that claims "All methods accept a
generic type parameter T" to clarify that only data-returning methods accept the
generic; explicitly exclude the delete method by name (delete(collection:
string, id: string, token?: string) -> Promise<{ deleted: boolean }>) and any
other non-data-returning methods from that blanket statement, e.g., rephrase to
"Methods that return documents accept a generic type parameter T (extending
DocumentData) so returned documents are fully typed; methods like delete(...)
return status objects and do not accept T."
In `@mintlify/docs/sdk/mail.mdx`:
- Around line 32-36: Update the SendMailResponse field types in the docs to
match the SDK contract: change the `id` field type to allow null (e.g., `string
| null`) and change the `provider` field from a generic `string` to the specific
literal union (`"byok" | "default"`), leaving `monthlyUsage` as `number`; ensure
these changes reference the SendMailResponse shape in the documentation so it
matches the SDK interface.
In `@mintlify/docs/sdk/overview.mdx`:
- Around line 38-60: Update the example to clearly indicate the mail/send usage
requires a server secret: change the urBackend initialization shown by the const
client = urBackend(...) example to explicitly show and label a server-only
secret key (e.g., reference process.env.URBACKEND_SECRET_KEY or similar) and add
a short inline comment that this initialization is server-side only; also keep
the existing client.auth.login and client.db calls unchanged but ensure the call
to client.mail.send is preceded or annotated to state “server secret required /
do not expose to clients” to prevent copy-paste misuse.
In `@mintlify/docs/sdk/schema.mdx`:
- Around line 24-33: The SchemaField documentation table is missing the items
and fields properties from the SDK type; update the SchemaField table to include
two new rows: add `items` (type `SchemaField` | `SchemaField[]` or `object` —
describe that it defines the element type for arrays, used when type is
`"Array"`) and `fields` (type `Record<string, SchemaField>` or `SchemaField[]` —
describe that it contains nested field definitions for object/embedded
documents), and ensure the descriptions explain when to use each (arrays vs
nested objects) and mention that `fields` is used when type is an object or
nested schema and `items` when type is an array.
In `@mintlify/docs/sdk/storage.mdx`:
- Around line 45-48: The example uses document.querySelector to get input and
then reads input.files[0] which can throw if the element isn't found or no file
is selected; add null-safety guards before accessing files: check that the
queried input element (variable input) is not null and that input.files exists
and has at least one entry (file) before assigning file and calling
client.storage.upload(file); if either check fails, handle gracefully (e.g. show
an error/return) so client.storage.upload is only called with a valid File
object.
---
Nitpick comments:
In `@mintlify/docs/sdk/auth.mdx`:
- Around line 109-176: Change heading text to sentence case and wrap method-name
headings in inline code formatting: update "Social Auth" to "Social auth",
"Account Verification" to "Account verification", "Manual Token Management" to
"Manual token management", and format method headings like socialStart,
socialExchange, publicProfile, and logout as `socialStart`, `socialExchange`,
`publicProfile`, and `logout`; ensure the examples and table entries use
backticks for method names (e.g., `verifyEmail`, `resendVerificationOtp`,
`requestPasswordReset`, `resetPassword`) so all code references follow the docs
style rules.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ba0038d8-92ae-477d-8466-af76fdb1dc5f
📒 Files selected for processing (7)
mintlify/docs/docs.jsonmintlify/docs/sdk/auth.mdxmintlify/docs/sdk/database.mdxmintlify/docs/sdk/mail.mdxmintlify/docs/sdk/overview.mdxmintlify/docs/sdk/schema.mdxmintlify/docs/sdk/storage.mdx
Generated-By: mintlify-agent
There was a problem hiding this comment.
Pull request overview
Synchronizes the Mintlify SDK documentation with the current @urbackend/sdk feature set by adding new module pages (Schema/Mail) and updating existing SDK docs for auth, database (incl. RLS + query params), and storage.
Changes:
- Added new SDK docs pages for
client.schema.getSchema()andclient.mail.send(). - Updated Auth and Database SDK docs to cover social auth, token rotation, RLS write patterns, QueryParams, and
patch(). - Updated SDK overview and sidebar navigation to include the expanded module list.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| mintlify/docs/docs.json | Adds sdk/schema and sdk/mail to the SDK navigation group. |
| mintlify/docs/sdk/overview.mdx | Refreshes quickstart snippet, key-security wording, and module cards (adds Schema/Mail). |
| mintlify/docs/sdk/auth.mdx | Expands auth docs with refresh token rotation, social auth, profile/security methods, and verification flows. |
| mintlify/docs/sdk/database.mdx | Adds RLS guidance, documents QueryParams usage, and introduces patch() alongside update/delete signatures. |
| mintlify/docs/sdk/storage.mdx | Updates upload return type to UploadResponse and documents provider plus revised limits. |
| mintlify/docs/sdk/schema.mdx | New page documenting schema introspection via client.schema.getSchema(). |
| mintlify/docs/sdk/mail.mdx | New page documenting transactional mail via client.mail.send() and secret-key requirement. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```typescript | ||
| const input = document.querySelector<HTMLInputElement>('input[type="file"]'); | ||
| const file = input.files[0]; | ||
|
|
||
| const { url, path } = await client.storage.upload(file); | ||
| const { url, path, provider } = await client.storage.upload(file); | ||
| console.log(url); // 'https://cdn.example.com/uploads/abc123.jpg' | ||
| console.log(path); // 'uploads/abc123.jpg' | ||
|
|
||
| // Store both so you can delete the file later | ||
| await client.db.insert('product_images', { url, path }); | ||
| ``` | ||
|
|
||
| **Example — custom filename** | ||
|
|
||
| ```typescript | ||
| const { url, path } = await client.storage.upload(file, 'profile-photo.jpg'); | ||
| ``` | ||
|
|
||
| **Example — Node.js Buffer** | ||
|
|
||
| ```typescript | ||
| import { readFileSync } from 'fs'; | ||
|
|
||
| const buffer = readFileSync('./report.pdf'); | ||
| const { url, path } = await client.storage.upload(buffer, 'report.pdf'); | ||
| console.log(provider); // 'internal' |
There was a problem hiding this comment.
This example shows calling client.storage.upload() from browser code (document.querySelector...). In the public API, /api/storage/* routes require a Secret Key (sk_live_...) via requireSecretKey, so browser usage with pk_live_... will fail (and using sk_live_... in the browser is unsafe). Consider changing the example to a server-side upload (or documenting a secure upload proxy/presigned flow) to avoid encouraging an unsupported/insecure browser pattern.
| ## Row-Level Security (RLS) | ||
|
|
||
| If a collection has RLS enabled, you must provide the user's `accessToken` to perform write operations (`insert`, `update`, `patch`, `delete`). | ||
|
|
||
| Example pattern: | ||
| ```typescript | ||
| interface DocumentData { | ||
| _id: string; | ||
| [key: string]: unknown; | ||
| } | ||
| const { accessToken } = await client.auth.login({ ... }); | ||
| await client.db.insert('posts', { content: 'Hello' }, accessToken); |
There was a problem hiding this comment.
The RLS section states you "must" provide the user's accessToken for all write operations. On the API side, Secret Keys bypass RLS write authorization checks, so the access token is only required when performing writes with a publishable key on an RLS-enabled collection. Please clarify this distinction (publishable-key + RLS vs secret-key server writes) so server-side users don’t think they need an end-user token.
| ## update | ||
|
|
||
| ```typescript | ||
| const product = await client.db.insert<Product>('products', { | ||
| name: 'Chair', | ||
| price: 99, | ||
| }); | ||
| Update an existing document by its ID. This performs a **full replacement** of the document fields. | ||
|
|
||
| console.log(product._id); // '507f1f77bcf86cd799439011' | ||
| ```typescript | ||
| update<T extends DocumentData>(collection: string, id: string, data: Record<string, unknown>, token?: string): Promise<T> | ||
| ``` |
There was a problem hiding this comment.
The update description says it performs a full replacement of the document. The current API handler for both PUT and PATCH applies $set updates (partial merge), so update() does not actually replace unspecified fields. Please adjust the wording to reflect the real behavior (or explicitly document that PUT and PATCH are currently equivalent).
| // Only updates the price, leaves other fields unchanged | ||
| await client.db.patch('products', 'id_123', { price: 45 }); |
There was a problem hiding this comment.
The patch() example omits the token argument even though the page earlier states write operations require the user's accessToken when RLS is enabled. Consider either passing accessToken in the example or adding a note that the token is only optional when using a Secret Key or when RLS is disabled, to avoid confusion for client-side/RLS users.
| // Only updates the price, leaves other fields unchanged | |
| await client.db.patch('products', 'id_123', { price: 45 }); | |
| // Only updates the price, leaves other fields unchanged. | |
| // Pass `accessToken` when RLS is enabled. | |
| await client.db.patch('products', 'id_123', { price: 45 }, accessToken); |
| **Returns** `AuthResponse` | ||
|
|
||
| ```typescript | ||
| interface AuthResponse { | ||
| token: string; // accessToken — store this securely | ||
| accessToken: string; | ||
| token: string; // Alias for accessToken (deprecated) | ||
| user: AuthUser; | ||
| expiresIn: string; | ||
| } |
There was a problem hiding this comment.
The documented AuthResponse interface marks accessToken, token, user, and expiresIn as required, but the SDK’s exported AuthResponse type has these fields optional (accessToken?, deprecated token?, expiresIn?, user?). Please align the docs with the actual SDK typings (or explicitly state which fields are guaranteed by the backend) so TypeScript users don’t get a false sense of strict guarantees.
| const urlParams = new URLSearchParams(window.location.search); | ||
| const rtCode = urlParams.get('rtCode'); | ||
| const token = new URLSearchParams(window.location.hash.slice(1)).get('token'); | ||
|
|
There was a problem hiding this comment.
In the socialExchange example, URLSearchParams.get() returns string | null, but SocialExchangePayload requires string fields. In a typescript code block this is a type error and could also lead to runtime issues if either value is missing. Add a small guard (or explicit non-null assertion with a comment) before calling socialExchange.
| if (!rtCode || !token) { | |
| throw new Error('Missing social auth callback parameters'); | |
| } |
mintlify/docs/sdk/auth.mdx
Outdated
| ## publicProfile | ||
|
|
||
| Fetch a public-safe profile for any user by their username. This does not return sensitive fields like email or provider IDs. | ||
|
|
||
| ```typescript | ||
| import urBackend, { AuthError } from '@urbackend/sdk'; | ||
| publicProfile(username: string): Promise<AuthUser> | ||
| ``` |
There was a problem hiding this comment.
This section says publicProfile returns a public-safe profile without sensitive fields like email, but the signature shows Promise<AuthUser> (where email is a required field in the SDK types). Consider documenting a dedicated return type (e.g. PublicProfile) or clarifying that the returned object is a subset of AuthUser, to avoid contradicting the text and confusing TypeScript users.
mintlify/docs/sdk/mail.mdx
Outdated
| | `id` | `string \| null` | The message ID from the provider (`null` if unavailable). | | ||
| | `provider` | `'byok' \| 'default'` | The provider used. | |
There was a problem hiding this comment.
SendMailResponse is documented with id: string and provider: string, but the SDK types define id as string | null and provider as a union ('byok' | 'default'). Please update the return table to reflect the actual SDK response typing (and note when id may be null).
| | `id` | `string \| null` | The message ID from the provider (`null` if unavailable). | | |
| | `provider` | `'byok' \| 'default'` | The provider used. | | |
| | `id` | `string \| null` | The message ID from the provider, or `null` if the provider does not return one. | | |
| | `provider` | `"byok"` \| `"default"` | The provider used. | |
Generated-By: mintlify-agent
yash-pouranik
temporarily deployed
to
docs/sdk/v0.2.2 - urBackend-frankfrut PR #92
Render
Destroyed
Generated-By: mintlify-agent
- auth.mdx: Make AuthResponse fields optional, add userId, use sentence-case headings, code-format method names, validate OAuth params before use - database.mdx: Clarify generic type T only applies to data-returning methods - mail.mdx: Fix id to string|null, provider to literal union type - overview.mdx: Use separate server client with secret key for mail example - schema.mdx: Add missing items and fields properties to SchemaField table - storage.mdx: Add null-safety guard for file input element Generated-By: mintlify-agent
|
Pushed a commit addressing all 7 CodeRabbit review comments: fixed AuthResponse to match SDK types (optional fields + userId), sentence-cased headings and code-formatted method names in auth.mdx, added null-safety guards in socialExchange and storage examples, corrected SendMailResponse types, clarified generic type parameter scope in database.mdx, added missing SchemaField properties (items/fields), and separated the server-side mail client with secret key in overview.mdx. |
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
mintlify/docs/sdk/auth.mdx (1)
7-7: Make explanatory lines consistently second-person.Line 7, Line 116, Line 149, Line 172, and Line 182 are mostly neutral/third-person. Prefer direct “you” phrasing for consistency.
Suggested edit
-Access auth methods via `client.auth`. The module automatically stores the `accessToken` ... +You can access auth methods via `client.auth`. The module stores the `accessToken` ... ... -Returns the URL to initiate the OAuth flow. +You receive a URL to initiate the OAuth flow. ... -Methods for handling email OTP flows. +Use these methods to handle email OTP flows.As per coding guidelines "Use active voice and second person ('you') in documentation writing".
Also applies to: 116-116, 149-149, 172-172, 182-182
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@mintlify/docs/sdk/auth.mdx` at line 7, Rewrite the neutral/third-person sentences on the specified lines to use active second-person voice; for example change phrasing around "Access auth methods via `client.auth`" and descriptions referencing `login()`, `refreshToken()`, `me()`, and `updateProfile()` so they address the reader as "you" (e.g., "You can access auth methods via `client.auth`" and "When you call `login()` or `refreshToken()`, the module stores the `accessToken` and uses it for subsequent authenticated requests such as `me()` or `updateProfile()`).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@mintlify/docs/sdk/auth.mdx`:
- Around line 9-10: The headings that contain API method names (for example the
"signUp" heading) must use inline code formatting; update each plain-text method
heading in auth.mdx (including the other occurrences noted) to wrap the
identifier in backticks (e.g., change "## signUp" to "## `signUp`") so all API
method names are consistently formatted as code.
- Line 110: The headings "Social Auth" (and the other two title-case section
titles at the same file) should be changed to sentence case; locate the headings
that currently read "Social Auth" and the other two title-cased headings in
auth.mdx and replace them with "Social auth" (and the corresponding
sentence-case forms) so all documentation headings follow the sentence-case
guideline.
---
Nitpick comments:
In `@mintlify/docs/sdk/auth.mdx`:
- Line 7: Rewrite the neutral/third-person sentences on the specified lines to
use active second-person voice; for example change phrasing around "Access auth
methods via `client.auth`" and descriptions referencing `login()`,
`refreshToken()`, `me()`, and `updateProfile()` so they address the reader as
"you" (e.g., "You can access auth methods via `client.auth`" and "When you call
`login()` or `refreshToken()`, the module stores the `accessToken` and uses it
for subsequent authenticated requests such as `me()` or `updateProfile()`).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 2b81c8bc-6823-49b9-a3c5-5663cb3fc6b7
📒 Files selected for processing (2)
mintlify/docs/sdk/auth.mdxmintlify/docs/sdk/mail.mdx
✅ Files skipped from review due to trivial changes (1)
- mintlify/docs/sdk/mail.mdx
Generated-By: mintlify-agent
Generated-By: mintlify-agent
yash-pouranik
temporarily deployed
to
docs/sdk/v0.2.2 - urBackend-frankfrut PR #92
Render
Destroyed
|
Updated auth.mdx to use second-person voice throughout (lines 7, 116, 149, 172, 182) and pushed the commit to the existing PR branch. |
|
@coderabbitai ok to merge? |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 41547
You're clear to merge! 🚀 |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: Length of output: 91763
✅ All CI checks passing:
✅ All review comments addressed across the follow-up commits:
You're clear to merge! 🚀 |
This PR synchronizes the official Mintlify documentation with the urbackend-sdk v0.2.0 release. It adds
documentation for all new modules, methods, and Row-Level Security (RLS) patterns that are now live in
production.
Key Updates
📖 New Documentation Pages
client.schema.getSchema().
including guidance on Secret Key requirements.
🔐 Authentication Coverage
🗄️ Database & RLS
relationship population (populate).
📦 Storage & UX
list.
Files Modified
This documentation update ensures developers have the necessary guidance to utilize the full feature set of the
latest SDK release.
Built with ❤️ for urBackend.
Summary by CodeRabbit
New Features
Documentation
Other