docs: add capacitor sdk guide

docs/sdk/native/capacitor-js/README.mdx

@@ -0,0 +1,41 @@
+---
+slug: /sdk/capacitor-js
+sidebar_label: Capacitor JS
+---
+
+import FurtherReadings from '../../fragments/_further-readings.md';
+
+import GetUserInformation from './_get-user-information.mdx';
+import GuideTip from './_guide-tip.md';
+import Installation from './_installation.mdx';
+import Integration from './_integration.mdx';
+import ApiResources from './api-resources/_index.mdx';
+
+# Integrate Logto with Capacitor JS
+
+<GuideTip />
+
+## Prerequisites
+
+- A [Logto Cloud](https://cloud.logto.io) account or a self-hosted Logto (Check out the [⚡ Get started](/docs/tutorials/get-started/) guide to create one if you don't have).
+- A Logto native application created.
+
+## Installation
+
+<Installation />
+
+## Integration
+
+<Integration />
+
+## Get user information
+
+<GetUserInformation />
+
+## API resources
+
+<ApiResources />
+
+## Further readings
+
+<FurtherReadings />

docs/sdk/native/capacitor-js/_get-user-information.mdx

@@ -0,0 +1,11 @@
+import GetUserInfoApis from '../../fragments/_get-user-info-apis.mdx';
+import ScopesAndClaims from '../../fragments/_scopes-and-claims.mdx';
+
+import ScopesAndClaimsCode from './_scopes-and-claims-code.md';
+
+<GetUserInfoApis
+  getIdTokenClaimsApi="logtoClient.getIdTokenClaims()"
+  fetchUserInfoApi="logtoClient.fetchUserInfo()"
+/>
+
+<ScopesAndClaims configScopesCode={<ScopesAndClaimsCode />} />

docs/sdk/native/capacitor-js/_guide-tip.md

@@ -0,0 +1,5 @@
+:::tip
+
+- The following demonstration is built on Capacitor JS 5.0.6.
+
+:::

docs/sdk/native/capacitor-js/_installation.mdx

@@ -0,0 +1,35 @@
+import TabItem from '@theme/TabItem';
+import Tabs from '@theme/Tabs';
+
+Install Logto SDK and peer dependencies via your favorite package manager:
+
+<Tabs>
+
+  <TabItem value="npm" label="npm">
+
+```bash
+npm i @logto/capacitor
+npm i @capacitor/browser @capacitor/app @capacitor/preferences
+```
+
+  </TabItem>
+  <TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add @logto/capacitor
+yarn add @capacitor/browser @capacitor/app @capacitor/preferences
+```
+
+  </TabItem>
+  <TabItem value="pnpm" label="pnpm">
+
+```bash
+pnpm add @logto/capacitor
+pnpm add @capacitor/browser @capacitor/app @capacitor/preferences
+```
+
+  </TabItem>
+
+</Tabs>
+
+The `@logto/capacitor` package is the SDK for Logto. The remaining packages are its peer dependencies.

docs/sdk/native/capacitor-js/_integration.mdx

@@ -0,0 +1,63 @@
+import SignInFlowSummary from '../../fragments/_web-sign-in-flow-summary.mdx';
+
+### Init Logto client
+
+Add the following code to your Capacitor project:
+
+```ts
+import LogtoClient, { type LogtoConfig } from '@logto/capacitor';
+
+const logtoConfig: LogtoConfig = {
+  endpoint: '<your-logto-endpoint>',
+  appId: '<your-application-id>',
+};
+
+const logtoClient = new LogtoClient(config);
+```
+
+### Implement sign-in
+
+<SignInFlowSummary />
+
+Now, let's configure the redirect URI. The redirect URI is used to redirect the user back to your application after the authentication flow.
+
+Ensure that the URI redirects to the Capacitor app, for example, `com.example.app://callback`. The value may vary depending on your Capacitor app configuration. For more details, see [Capacitor Deep Links](https://capacitorjs.com/docs/guides/deep-links).
+
+Then, add the following code to the onClick handler of the sign-in button:
+
+```ts
+const onClick = async () => {
+  await logtoClient.signIn('com.example.app://callback');
+  console.log(await logtoClient.isAuthenticated()); // true
+  console.log(await logtoClient.getIdTokenClaims()); // { sub: '...', ... }
+};
+```
+
+### Checkpoint: Trigger the authentication flow
+
+Run the Capacitor app and click the sign-in button. A browser window will open, redirecting to the Logto sign-in page.
+
+If the user closes the browser window without completing the authentication flow, the Capacitor app will receive a `LogtoClientError`.
+
+### Implement sign-out
+
+Since Capacitor leverages the Safari View Controller on iOS and Chrome Custom Tabs on Android, the authentication state can be persisted for a while. However, sometimes the user may want to sign out of the application immediately. In this case, we can use the `signOut` method to sign out the user:
+
+```ts
+const onClick = async () => {
+  await logtoClient.signOut();
+  console.log(await logtoClient.isAuthenticated()); // false
+};
+```
+
+The `signOut` method has an optional parameter for the post sign-out redirect URI. If it's not provided, the user will be redirected to the Logto sign-out page.
+
+The user needs to click "Done" to close the web view and return to the Capacitor app. If you want to automatically redirect the user back to the Capacitor app, you can provide the post sign-out redirect URI, for instance, `com.example.app://callback/sign-out`.
+
+Ensure that the post sign-out redirect URI can redirect to the Capacitor app. Then add the following code to the onClick handler of the sign-out button:
+
+```ts
+const onClick = async () => {
+  await logtoClient.signOut('com.example.app://callback/sign-out');
+};
+```

docs/sdk/native/capacitor-js/_scopes-and-claims-code.md

@@ -0,0 +1,8 @@
+```ts
+import { type LogtoConfig, UserScope } from '@logto/capacitor';
+
+const config: LogtoConfig = {
+  // ...other options
+  scopes: [UserScope.Email, UserScope.Phone], // Add the scopes you need
+};
+```

docs/sdk/native/capacitor-js/api-resources/_config-api-resources.mdx

@@ -0,0 +1,11 @@
+import ConfigApiResources from '../../../fragments/_config-api-resources.mdx';
+
+import ConfigResourcesCode from './code/_config-resources-code.md';
+import ConfigResourcesWithScopesCode from './code/_config-resources-with-scopes-code.md';
+import ConfigResourcesWithSharedScopesCode from './code/_config-resources-with-shared-scopes-code.md';
+
+<ConfigApiResources
+  configResourcesCode={<ConfigResourcesCode />}
+  configResourcesWithScopesCode={<ConfigResourcesWithScopesCode />}
+  configResourcesWithSharedScopesCode={<ConfigResourcesWithSharedScopesCode />}
+/>

docs/sdk/native/capacitor-js/api-resources/_fetch-access-token-for-api-resources.mdx

@@ -0,0 +1,8 @@
+import FetchAccessTokenForApiResources from '../../../fragments/_fetch-access-token-for-api-resources.mdx';
+
+import GetAccessTokenCode from './code/_get-access-token-code.md';
+
+<FetchAccessTokenForApiResources
+  getAccessTokenApi="getAccessToken"
+  getAccessTokenCode={<GetAccessTokenCode />}
+/>

docs/sdk/native/capacitor-js/api-resources/_fetch-organization-token-for-user.mdx

@@ -0,0 +1,10 @@
+import FetchOrganizationTokenForUser from '../../../fragments/_fetch-organization-token-for-user.mdx';
+
+import ConfigOrganizationCode from './code/_config-organization-code.md';
+import GetOrganizationAccessTokenCode from './code/_get-organization-access-token-code.md';
+
+<FetchOrganizationTokenForUser
+  organizationScope="UserScope.Organizations"
+  configOrganizationCode={<ConfigOrganizationCode />}
+  getOrganizationAccessTokenCode={<GetOrganizationAccessTokenCode />}
+/>

docs/sdk/native/capacitor-js/api-resources/_index.mdx

@@ -0,0 +1,19 @@
+import ApiResourcesDescription from '../../../fragments/_api-resources-description.md';
+
+import ConfigApiResources from './_config-api-resources.mdx';
+import FetchAccessTokenForApiResources from './_fetch-access-token-for-api-resources.mdx';
+import FetchOrganizationTokenForUser from './_fetch-organization-token-for-user.mdx';
+
+<ApiResourcesDescription />
+
+### Configure Logto client
+
+<ConfigApiResources />
+
+### Fetch access token for the API resource
+
+<FetchAccessTokenForApiResources />
+
+### Fetch organization token for user
+
+<FetchOrganizationTokenForUser />

docs/sdk/native/capacitor-js/api-resources/code/_config-organization-code.md

@@ -0,0 +1,8 @@
+```ts
+import { type LogtoConfig, UserScope } from '@logto/capacitor';
+
+const config: LogtoConfig = {
+  // ...other configs
+  scopes: [UserScope.Organizations],
+};
+```

docs/sdk/native/capacitor-js/api-resources/code/_config-resources-code.md

@@ -0,0 +1,9 @@
+```tsx
+import { type LogtoConfig } from '@logto/capacitor';
+
+const config: LogtoConfig = {
+  appId: '<your-application-id>',
+  endpoint: '<your-logto-endpoint>',
+  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'], // Add API resources
+};
+```

docs/sdk/native/capacitor-js/api-resources/code/_config-resources-with-scopes-code.md

@@ -0,0 +1,10 @@
+```tsx
+import { type LogtoConfig } from '@logto/capacitor';
+
+const config: LogtoConfig = {
+  appId: '<your-application-id>',
+  endpoint: '<your-logto-endpoint>',
+  scopes: ['shopping:read', 'shopping:write', 'store:read', 'store:write'],
+  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
+};
+```

docs/sdk/native/capacitor-js/api-resources/code/_config-resources-with-shared-scopes-code.md

@@ -0,0 +1,10 @@
+```tsx
+import { type LogtoConfig } from '@logto/capacitor';
+
+const config: LogtoConfig = {
+  appId: '<your-application-id>',
+  endpoint: '<your-logto-endpoint>',
+  scopes: ['read', 'write'],
+  resources: ['https://shopping.your-app.com/api', 'https://store.your-app.com/api'],
+};
+```

docs/sdk/native/capacitor-js/api-resources/code/_get-access-token-code.md

@@ -0,0 +1,3 @@
+```tsx
+const token = await logtoClient.getAccessToken('https://shopping.your-app.com/api');
+```

docs/sdk/native/capacitor-js/api-resources/code/_get-organization-access-token-code.md

@@ -0,0 +1,3 @@
+```tsx
+await logtoClient.getOrganizationToken(organizationId);
+```

docs/sdk/native/expo/_integration.mdx

@@ -61,7 +61,7 @@ const Content = () => {
 
 ### Display user information
 
-To display the user's information, you use the `getIdTokenClaims()` method:
+To display the user's information, you can use the `getIdTokenClaims()` method:
 
 ```tsx
 import { useLogto } from '@logto/rn';