diff --git a/skills/base44-cli/SKILL.md b/skills/base44-cli/SKILL.md index 549634b..b68e599 100644 --- a/skills/base44-cli/SKILL.md +++ b/skills/base44-cli/SKILL.md @@ -104,8 +104,10 @@ my-app/ │ │ └── my-function/ │ │ ├── function.jsonc │ │ └── index.ts -│ └── agents/ # Agent configurations (optional) -│ └── support_agent.jsonc +│ ├── agents/ # Agent configurations (optional) +│ │ └── support_agent.jsonc +│ └── connectors/ # OAuth connector configurations (optional) +│ └── googlecalendar.jsonc ├── src/ # Frontend source code │ ├── api/ │ │ └── base44Client.js # Base44 SDK client @@ -121,6 +123,7 @@ my-app/ - `base44/config.jsonc` - Project name, description, site build settings - `base44/entities/*.jsonc` - Data model schemas (see Entity Schema section) - `base44/agents/*.jsonc` - Agent configurations (optional) +- `base44/connectors/*.jsonc` - OAuth connector configurations (optional) - `src/api/base44Client.js` - Pre-configured SDK client for frontend use **config.jsonc example:** @@ -131,6 +134,7 @@ my-app/ "entitiesDir": "./entities", // Optional: default "entities" "functionsDir": "./functions", // Optional: default "functions" "agentsDir": "./agents", // Optional: default "agents" + "connectorsDir": "./connectors", // Optional: default "connectors" "site": { // Optional: site deployment config "installCommand": "npm install", // Optional: install dependencies "buildCommand": "npm run build", // Optional: build command @@ -149,6 +153,7 @@ my-app/ | `entitiesDir` | Directory for entity schemas | `"entities"` | | `functionsDir` | Directory for backend functions | `"functions"` | | `agentsDir` | Directory for agent configs | `"agents"` | +| `connectorsDir` | Directory for connector configs | `"connectors"` | | `site.installCommand` | Command to install dependencies | - | | `site.buildCommand` | Command to build the project | - | | `site.serveCommand` | Command to run dev server | - | @@ -283,6 +288,53 @@ Agents are conversational AI assistants that can interact with users, access you - **Entity tools**: `entity_name` + `allowed_operations` (array of: `read`, `create`, `update`, `delete`) - **Backend function tools**: `function_name` + `description` +### Connector Management + +Connectors are OAuth integrations that let your app connect to external services (Google Calendar, Slack, Notion, etc.). They provide access tokens that you can use in backend functions to call external APIs. + +| Action / Command | Description | Reference | +| --------------------------- | ----------------------------------------------- | ----------------------------------------------------- | +| Create Connectors | Define connectors in `base44/connectors` folder | [connectors-create.md](references/connectors-create.md) | +| `base44 connectors push` | Push local connectors to Base44 | [connectors-push.md](references/connectors-push.md) | + +**Note:** Pushing connectors syncs scopes and removes any connectors not defined locally. New connectors require OAuth authorization in your browser. + +#### Connector Schema (Quick Reference) + +**File naming:** `base44/connectors/{type}.jsonc` (e.g., `googlecalendar.jsonc`, `slack.jsonc`) + +**Schema template:** +```jsonc +{ + "type": "googlecalendar", + "scopes": [ + "https://www.googleapis.com/auth/calendar.readonly", + "https://www.googleapis.com/auth/calendar.events" + ] +} +``` + +**Required fields:** `type` +**Optional fields:** `scopes` (defaults to `[]`) + +**Supported connector types:** +| Service | Type | +|---------|------| +| Google Calendar | `googlecalendar` | +| Google Drive | `googledrive` | +| Google Sheets | `googlesheets` | +| Google Docs | `googledocs` | +| Google Slides | `googleslides` | +| Gmail | `gmail` | +| Slack | `slack` | +| Notion | `notion` | +| Salesforce | `salesforce` | +| HubSpot | `hubspot` | +| LinkedIn | `linkedin` | +| TikTok | `tiktok` | + +For complete documentation, see [connectors-create.md](references/connectors-create.md). + ### Site Deployment | Command | Description | Reference | @@ -318,6 +370,7 @@ Or deploy individual resources: - `npx base44 entities push` - Push entities only - `npx base44 functions deploy` - Deploy functions only - `npx base44 agents push` - Push agents only +- `npx base44 connectors push` - Push connectors only - `npx base44 site deploy -y` - Deploy site only ## Common Workflows @@ -357,6 +410,9 @@ npx base44 functions deploy # Push only agents npx base44 agents push +# Push only connectors +npx base44 connectors push + # Deploy only site npx base44 site deploy -y ``` @@ -381,5 +437,9 @@ Most commands require authentication. If you're not logged in, the CLI will auto | No functions found | Ensure functions exist in `base44/functions/` with valid `function.jsonc` configs | | No agents found | Ensure agents exist in `base44/agents/` directory with valid `.jsonc` configs | | Invalid agent name | Agent names must be lowercase alphanumeric with underscores only | +| No connectors found | Ensure connectors exist in `base44/connectors/` directory with valid `.jsonc` configs | +| Invalid connector type | Connector `type` must be one of the supported services (googlecalendar, slack, etc.) | +| Duplicate connector type | Each connector type can only be defined once per project | +| Connector authorization timeout | Re-run `npx base44 connectors push` and complete the OAuth flow in your browser | | No site configuration found | Check that `site.outputDirectory` is configured in project config | | Site deployment fails | Ensure you ran `npm run build` first and the build succeeded | diff --git a/skills/base44-cli/references/connectors-create.md b/skills/base44-cli/references/connectors-create.md new file mode 100644 index 0000000..db92a99 --- /dev/null +++ b/skills/base44-cli/references/connectors-create.md @@ -0,0 +1,128 @@ +# Creating Connectors + +Connectors are OAuth integrations that let your Base44 app connect to external services like Google Calendar, Slack, Notion, and more. Once connected, you can use access tokens in backend functions to call external APIs directly. + +## Key Concepts + +- **Direct API Access**: Connectors provide raw OAuth access tokens - you call the external APIs directly from backend functions +- **App Builder's Account**: Connects your account (the app builder), not your end users' accounts +- **Backend Functions Only**: Tokens are only accessible server-side for security + +## File Location + +Create connector files in the `base44/connectors/` directory (or the directory specified by `connectorsDir` in your config.jsonc). + +**File naming:** `{type}.jsonc` or `{type}.json` + +Examples: +- `base44/connectors/googlecalendar.jsonc` +- `base44/connectors/slack.jsonc` +- `base44/connectors/notion.json` + +## Schema + +Each connector file must specify a `type` and optionally a list of `scopes`: + +```jsonc +{ + "type": "googlecalendar", + "scopes": [ + "https://www.googleapis.com/auth/calendar.readonly", + "https://www.googleapis.com/auth/calendar.events" + ] +} +``` + +### Fields + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `type` | string | Yes | The integration type (see supported types below) | +| `scopes` | string[] | No | OAuth scopes to request (defaults to `[]`) | + +## Supported Connector Types + +| Service | Type | Scopes Documentation | +|---------|------|---------------------| +| Google Calendar | `googlecalendar` | [Google Calendar Scopes](https://developers.google.com/identity/protocols/oauth2/scopes#calendar) | +| Google Drive | `googledrive` | [Google Drive Scopes](https://developers.google.com/identity/protocols/oauth2/scopes#drive) | +| Google Sheets | `googlesheets` | [Google Sheets Scopes](https://developers.google.com/identity/protocols/oauth2/scopes#sheets) | +| Google Docs | `googledocs` | [Google Docs Scopes](https://developers.google.com/identity/protocols/oauth2/scopes#docs) | +| Google Slides | `googleslides` | [Google Slides Scopes](https://developers.google.com/identity/protocols/oauth2/scopes#slides) | +| Gmail | `gmail` | [Gmail Scopes](https://developers.google.com/identity/protocols/oauth2/scopes#gmail) | +| Slack | `slack` | [Slack Scopes](https://api.slack.com/scopes) | +| Notion | `notion` | [Notion Authorization](https://developers.notion.com/docs/authorization) | +| Salesforce | `salesforce` | [Salesforce Scopes](https://developer.salesforce.com/docs/platform/mobile-sdk/guide/oauth-scope-parameter-values.html) | +| HubSpot | `hubspot` | [HubSpot Scopes](https://developers.hubspot.com/docs/api/scopes) | +| LinkedIn | `linkedin` | [LinkedIn Scopes](https://learn.microsoft.com/en-us/linkedin/marketing/increasing-access) | +| TikTok | `tiktok` | [TikTok Scopes](https://developers.tiktok.com/doc/scopes-overview) | + +## Examples + +### Google Calendar (Read and Write Events) + +```jsonc +// base44/connectors/googlecalendar.jsonc +{ + "type": "googlecalendar", + "scopes": [ + "https://www.googleapis.com/auth/calendar.readonly", + "https://www.googleapis.com/auth/calendar.events" + ] +} +``` + +### Slack (Send Messages and Read Channels) + +```jsonc +// base44/connectors/slack.jsonc +{ + "type": "slack", + "scopes": [ + "chat:write", + "channels:read" + ] +} +``` + +### Notion (Default Access) + +```jsonc +// base44/connectors/notion.jsonc +{ + "type": "notion", + "scopes": [] +} +``` + +Note: Notion uses a page-based access model where users select which pages to share during OAuth authorization. + +### Google Sheets (Read Only) + +```jsonc +// base44/connectors/googlesheets.jsonc +{ + "type": "googlesheets", + "scopes": [ + "https://www.googleapis.com/auth/spreadsheets.readonly" + ] +} +``` + +## Rules and Constraints + +1. **One connector per type**: You cannot have multiple connectors of the same type (e.g., two `googlecalendar` connectors) + +2. **Type must be valid**: The `type` field must be one of the supported connector types listed above + +3. **Scopes are provider-specific**: Each service has its own scope format - refer to the provider's documentation + +## Next Steps + +After creating connector files, push them to Base44: + +```bash +npx base44 connectors push +``` + +This will prompt you to authorize each new connector in your browser. See [connectors-push.md](connectors-push.md) for details. diff --git a/skills/base44-cli/references/connectors-push.md b/skills/base44-cli/references/connectors-push.md new file mode 100644 index 0000000..844bef8 --- /dev/null +++ b/skills/base44-cli/references/connectors-push.md @@ -0,0 +1,120 @@ +# base44 connectors push + +Push local connector configurations to Base44, synchronizing scopes and handling OAuth authorization. + +## Usage + +```bash +npx base44 connectors push +``` + +## What It Does + +1. **Reads local connectors** from your `base44/connectors/` directory +2. **Syncs with Base44** - updates scopes for existing connectors +3. **Adds new connectors** - any new connector types trigger OAuth authorization +4. **Removes unlisted connectors** - connectors not in your local files are removed from Base44 + +## OAuth Authorization Flow + +When you add a new connector, it needs to be authorized: + +1. The CLI detects which connectors need authorization +2. You're prompted: "Open browser to authorize now?" +3. If you accept, the browser opens to the OAuth provider (Google, Slack, etc.) +4. You log into your account and approve the requested permissions +5. The browser closes and the CLI confirms authorization + +**Important**: You choose which account to connect by logging into it during the OAuth flow. For example, if you have multiple Google accounts, you select which one to use in the Google login screen. + +## Example Output + +### Pushing connectors (no new authorization needed) + +``` +Found 2 connectors to push: googlecalendar, slack +✓ Connectors pushed + +Summary: + Synced: googlecalendar, slack +``` + +### Pushing new connectors (authorization required) + +``` +Found 3 connectors to push: googlecalendar, slack, notion +✓ Connectors pushed + +2 connector(s) require authorization in your browser: + slack: https://auth.base44.io/oauth/... + notion: https://auth.base44.io/oauth/... + +? Open browser to authorize now? › Yes + +Opening browser for slack... +✓ slack authorization complete + +Opening browser for notion... +✓ notion authorization complete + +Summary: + Synced: googlecalendar + Added: slack, notion +``` + +### Removing connectors + +If you delete a connector file locally and push, it will be removed: + +``` +Found 1 connectors to push: googlecalendar +✓ Connectors pushed + +Summary: + Synced: googlecalendar + Removed: slack +``` + +## CI/CD Environments + +In CI environments (when `CI` environment variable is set), the OAuth flow is skipped automatically: + +``` +Skipped OAuth in CI. Pending: slack, notion. Run 'base44 connectors push' locally to authorize. +``` + +You must run `npx base44 connectors push` locally to complete authorization for new connectors. + +## Skipping Authorization + +If you choose not to authorize immediately, the connectors remain in a pending state: + +``` +? Open browser to authorize now? › No + +Authorization skipped. Pending: slack, notion. Run 'base44 connectors push' again to complete. +``` + +Run the command again when you're ready to authorize. + +## Summary Status Meanings + +| Status | Meaning | +|--------|---------| +| Synced | Connector already existed, scopes updated if needed | +| Added | New connector successfully authorized | +| Removed | Connector was deleted from Base44 (not in local files) | +| Failed | Authorization timed out, failed, or was skipped | + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| Authorization timed out | Re-run `npx base44 connectors push` and complete OAuth faster | +| Authorization failed | Check that you approved all requested permissions | +| Wrong account connected | Remove the connector file, push to delete it, then add it back and authorize with the correct account | +| Browser didn't open | Copy the URL shown in the terminal and open it manually | + +## Related Commands + +- [connectors-create.md](connectors-create.md) - How to create connector configuration files