@slates-integrations/tableau 0.2.0-rc.8

package/README.md

@@ -0,0 +1,85 @@
+# <img src="https://provider-logos.metorial-cdn.com/tableau.png" height="20"> Tableau
+
+Manage Tableau Cloud and Tableau Server resources programmatically through the Tableau REST API. Query and manage workbooks, data sources, views, custom views, flows, users, groups, projects, permissions, favorites, collections, jobs, and data-driven alerts. Export views as CSV, PNG, or PDF. Authentication supports Tableau personal access tokens, username/password sign-in, and connected-app or unified-access-token JWT sign-in.
+
+## Tools
+
+### Get Site Info
+
+Retrieve information about the current Tableau site, including name, URL, storage usage, and configuration settings.
+
+### Get View Data
+
+Export the underlying data from a Tableau view as CSV. Useful for retrieving the tabular data behind a dashboard visualization.
+
+### Export View
+
+Export a Tableau view as CSV data, a PNG image, or a PDF file. Supports Tableau view filter query parameters and cache max-age controls.
+
+### List Data Sources
+
+List and search data sources on the Tableau site. Supports pagination, filtering, and sorting.
+
+### List Views
+
+List and search views across the Tableau site. Supports pagination, filtering, and sorting.
+
+### List Workbooks
+
+List and search workbooks on the Tableau site. Supports pagination, filtering, and sorting to find specific workbooks.
+
+### Manage Data-Driven Alerts
+
+List, get, delete data-driven alerts, and add or remove users from alert recipient lists. Data-driven alerts trigger when data in a view meets specified conditions.
+
+### Manage Collections
+
+List, get, create, update, or delete collections, and add, remove, or list collection items. Collections are curated groups of Tableau content.
+
+### Manage Custom Views
+
+List, get, update, delete, or export Tableau custom views. Custom views are saved user-specific configurations of workbook views.
+
+### Manage Data Source
+
+Get details, update, delete, or trigger extract refresh for a data source. Use the **action** field to select the operation.
+
+### Manage Favorites
+
+List, add, or remove favorites for a user. Supports workbooks, views, data sources, projects, and flows.
+
+### Manage Flows
+
+List, get, update, delete, or run Tableau Prep flows. Use the **action** field to select the operation.
+
+### Manage Groups
+
+List, create, update, delete groups, and add or remove users from groups. Use the **action** field to select the operation.
+
+### Manage Jobs
+
+List, get details, or cancel background jobs (extract refreshes, flow runs, subscriptions). Use the **action** field to select the operation.
+
+### Manage Permissions
+
+Query, add, or delete permissions on Tableau resources (workbooks, datasources, projects, views, flows). Permissions are granted to users or groups with specific capability modes.
+
+### Manage Projects
+
+List, create, update, or delete projects. Projects organize workbooks, data sources, and other content in Tableau.
+
+### Manage Users
+
+List, get, add, update, or remove users on the Tableau site. Use the **action** field to select the operation.
+
+### Manage Workbook
+
+Get details, update properties, delete, refresh extracts, or manage tags for a workbook. Use the **action** field to select the operation.
+
+## License
+
+This integration is licensed under the [FSL-1.1](https://github.com/metorial/metorial-platform/blob/dev/LICENSE).
+
+<div align="center">
+  <sub>Built with ❤️ by <a href="https://metorial.com">Metorial</a></sub>
+</div>

package/docs/SPEC.md

@@ -0,0 +1,61 @@
+# Tableau Integration Specification
+
+## Overview
+
+This integration uses Tableau's REST API to manage common Tableau Cloud and Tableau Server resources. It focuses on practical content and administration workflows: querying content, exporting views, managing users and groups, managing projects and permissions, monitoring jobs, managing favorites, managing current collections endpoints, and handling custom views and data-driven alerts.
+
+The default REST API version is `3.28`, matching Tableau 2026.1 documentation. Classic endpoints use `/api/{api-version}/sites/{site-luid}`. Current collections CRUD and item endpoints use Tableau's per-resource path under `/api/-/collections`.
+
+## Authentication
+
+The integration signs in to Tableau and stores the returned credentials token, site LUID, user LUID, estimated expiration time, and auth method.
+
+Supported sign-in methods:
+
+- Personal access token (PAT)
+- Username and password
+- Connected app JWT
+- Unified access token JWT by setting `isUat: true`
+
+Tableau credentials tokens expire. Tableau Cloud tokens are documented as valid for 120 minutes, while Tableau Server tokens are typically valid for 240 minutes unless the server setting has changed. The integration records a conservative estimated expiration and can refresh PAT and username/password profiles by signing in again with the stored auth input. Non-refreshable auth methods report a user-facing `ServiceError` if a stored token is already expired.
+
+## Tools
+
+- `get_site_info`: Get current site details.
+- `list_workbooks`: List and filter workbooks.
+- `manage_workbook`: Get, update, delete, refresh, and tag workbooks.
+- `list_datasources`: List and filter published data sources.
+- `manage_datasource`: Get, update, delete, and refresh data sources.
+- `list_views`: List and filter views.
+- `get_view_data`: Export view underlying data as CSV.
+- `export_view`: Export a view as CSV, PNG, or PDF.
+- `manage_custom_views`: List, get, update, delete, and export custom views.
+- `manage_users`: List, get, add, update, and remove site users.
+- `manage_groups`: List, create, update, delete groups, and manage group membership.
+- `manage_projects`: List, create, update, and delete projects.
+- `manage_permissions`: Query, add, and delete permissions for supported Tableau resources.
+- `manage_jobs`: List, get, and cancel background jobs.
+- `manage_favorites`: List, add, and remove user favorites.
+- `manage_flows`: List, get, update, delete, and run flows.
+- `manage_collections`: List, get, create, update, delete collections, and add, remove, or list collection items.
+- `manage_alerts`: List, get, delete, and manage recipients for data-driven alerts.
+
+## Error Handling
+
+Tool validation failures, auth failures, and upstream Tableau API failures are normalized to `ServiceError` from `@lowerdeck/error`. Upstream failures preserve the HTTP status when Tableau provides one.
+
+## Live E2E
+
+The private live E2E suite lives at `tests/integrations/tableau/tools.e2e.ts`. Stable content IDs can be supplied through `SLATES_E2E_FIXTURES`:
+
+- `workbookId`
+- `datasourceId`
+- `viewId`
+- `userId`
+- `groupId`
+- `customViewId`
+- `collectionItemContentLuid`
+- `collectionItemContentType`
+- `collectionItemContentName`
+
+The suite creates and deletes its own collection for collection CRUD coverage.

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@slates-integrations/tableau",
+  "main": "src/index.ts",
+  "type": "module",
+  "scripts": {
+    "build": "bunx @vercel/ncc build src/index.ts -o dist -m -s",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@lowerdeck/error": "^1.1.0",
+    "@types/node": "^20",
+    "slates": "1.0.0-rc.10",
+    "zod": "^4.2"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "version": "0.2.0-rc.8"
+}

package/slate.json

@@ -0,0 +1,18 @@
+{
+  "name": "@metorial/tableau",
+  "description": "Manage Tableau Cloud and Tableau Server resources through the Tableau REST API. Query and manage workbooks, data sources, views, custom views, flows, users, groups, projects, permissions, favorites, collections, jobs, and data-driven alerts. Export views as CSV, PNG, or PDF.",
+  "categories": ["apis-and-http-requests", "document-processing"],
+  "skills": [
+    "query and manage workbooks",
+    "export views as CSV, PNG, or PDF",
+    "manage data source extracts",
+    "administer users and groups",
+    "configure permissions",
+    "monitor background jobs",
+    "manage flows and runs",
+    "manage data-driven alerts",
+    "manage collections and favorites",
+    "manage custom views"
+  ],
+  "logoUrl": "https://provider-logos.metorial-cdn.com/tableau.png"
+}

package/src/auth.ts

@@ -0,0 +1,237 @@
+import { SlateAuth, createAxios } from 'slates';
+import { z } from 'zod';
+import { tableauApiError, tableauServiceError } from './lib/errors';
+
+type TableauAuthOutput = {
+  token: string;
+  siteId: string;
+  userId: string;
+  expiresAt?: string;
+  authMethod?: 'personal_access_token' | 'username_password' | 'connected_app_jwt';
+};
+
+type TableauSignInInput = {
+  serverUrl: string;
+  siteContentUrl: string;
+  apiVersion: string;
+};
+
+type TableauPersonalAccessTokenInput = TableauSignInInput & {
+  tokenName: string;
+  tokenSecret: string;
+};
+
+type TableauUsernamePasswordInput = TableauSignInInput & {
+  username: string;
+  password: string;
+};
+
+type TableauConnectedAppJwtInput = TableauSignInInput & {
+  jwt: string;
+  isUat?: boolean;
+};
+
+type TableauRefreshContext<Input> = {
+  output: TableauAuthOutput;
+  input: Input;
+  clientId: string;
+  clientSecret: string;
+  scopes: string[];
+};
+
+let estimateTokenExpiresAt = (serverUrl: string) => {
+  let lifetimeMinutes = /\.online\.tableau\.com/i.test(serverUrl) ? 110 : 230;
+  return new Date(Date.now() + lifetimeMinutes * 60 * 1000).toISOString();
+};
+
+let signIn = async (
+  input: TableauSignInInput,
+  credentials: Record<string, unknown>,
+  authMethod: NonNullable<TableauAuthOutput['authMethod']>
+) => {
+  let baseUrl = input.serverUrl.replace(/\/+$/, '');
+  let http = createAxios({ baseURL: baseUrl });
+
+  try {
+    let response = await http.post(`/api/${input.apiVersion}/auth/signin`, {
+      credentials: {
+        ...credentials,
+        site: {
+          contentUrl: input.siteContentUrl
+        }
+      }
+    });
+
+    let responseCredentials = response.data?.credentials;
+    if (
+      !responseCredentials?.token ||
+      !responseCredentials?.site?.id ||
+      !responseCredentials?.user?.id
+    ) {
+      throw tableauServiceError(
+        'Tableau sign-in response did not include token, site ID, and user ID.'
+      );
+    }
+
+    return {
+      output: {
+        token: responseCredentials.token,
+        siteId: responseCredentials.site.id,
+        userId: responseCredentials.user.id,
+        expiresAt: estimateTokenExpiresAt(input.serverUrl),
+        authMethod
+      }
+    };
+  } catch (error) {
+    throw tableauApiError(error, 'sign-in');
+  }
+};
+
+let getProfile = async (ctx: { output: TableauAuthOutput; input: any }) => {
+  return {
+    profile: {
+      id: ctx.output.userId,
+      siteId: ctx.output.siteId,
+      authMethod: ctx.output.authMethod,
+      expiresAt: ctx.output.expiresAt
+    }
+  };
+};
+
+let personalAccessTokenAuth = {
+  type: 'auth.custom' as const,
+  name: 'Personal Access Token',
+  key: 'personal_access_token',
+
+  inputSchema: z.object({
+    serverUrl: z.string().describe('Tableau Server or Cloud URL'),
+    siteContentUrl: z.string().default('').describe('Site content URL'),
+    apiVersion: z.string().default('3.28').describe('API version'),
+    tokenName: z.string().describe('Personal access token name'),
+    tokenSecret: z.string().describe('Personal access token secret')
+  }),
+
+  getOutput: async (ctx: { input: TableauPersonalAccessTokenInput }) => {
+    let { serverUrl, siteContentUrl, apiVersion, tokenName, tokenSecret } = ctx.input;
+
+    return await signIn(
+      { serverUrl, siteContentUrl, apiVersion },
+      {
+        personalAccessTokenName: tokenName,
+        personalAccessTokenSecret: tokenSecret
+      },
+      'personal_access_token'
+    );
+  },
+
+  handleTokenRefresh: async (
+    ctx: TableauRefreshContext<TableauPersonalAccessTokenInput>
+  ) => {
+    let { serverUrl, siteContentUrl, apiVersion, tokenName, tokenSecret } = ctx.input;
+
+    return await signIn(
+      { serverUrl, siteContentUrl, apiVersion },
+      {
+        personalAccessTokenName: tokenName,
+        personalAccessTokenSecret: tokenSecret
+      },
+      'personal_access_token'
+    );
+  },
+
+  getProfile
+};
+
+let usernamePasswordAuth = {
+  type: 'auth.custom' as const,
+  name: 'Username & Password',
+  key: 'username_password',
+
+  inputSchema: z.object({
+    serverUrl: z.string().describe('Tableau Server or Cloud URL'),
+    siteContentUrl: z.string().default('').describe('Site content URL'),
+    apiVersion: z.string().default('3.28').describe('API version'),
+    username: z.string().describe('Tableau username'),
+    password: z.string().describe('Tableau password')
+  }),
+
+  getOutput: async (ctx: { input: TableauUsernamePasswordInput }) => {
+    let { serverUrl, siteContentUrl, apiVersion, username, password } = ctx.input;
+
+    return await signIn(
+      { serverUrl, siteContentUrl, apiVersion },
+      {
+        name: username,
+        password
+      },
+      'username_password'
+    );
+  },
+
+  handleTokenRefresh: async (ctx: TableauRefreshContext<TableauUsernamePasswordInput>) => {
+    let { serverUrl, siteContentUrl, apiVersion, username, password } = ctx.input;
+
+    return await signIn(
+      { serverUrl, siteContentUrl, apiVersion },
+      {
+        name: username,
+        password
+      },
+      'username_password'
+    );
+  },
+
+  getProfile
+};
+
+let connectedAppJwtAuth = {
+  type: 'auth.custom' as const,
+  name: 'Connected App JWT',
+  key: 'connected_app_jwt',
+
+  inputSchema: z.object({
+    serverUrl: z.string().describe('Tableau Server or Cloud URL'),
+    siteContentUrl: z.string().default('').describe('Site content URL'),
+    apiVersion: z.string().default('3.28').describe('API version'),
+    jwt: z.string().describe('JWT generated for a Tableau connected app or UAT'),
+    isUat: z
+      .boolean()
+      .optional()
+      .describe('Set true when signing in with a Tableau Cloud unified access token JWT')
+  }),
+
+  getOutput: async (ctx: { input: TableauConnectedAppJwtInput }) => {
+    let { serverUrl, siteContentUrl, apiVersion, jwt, isUat } = ctx.input;
+
+    return await signIn(
+      { serverUrl, siteContentUrl, apiVersion },
+      {
+        jwt,
+        ...(isUat !== undefined ? { isUat } : {})
+      },
+      'connected_app_jwt'
+    );
+  },
+
+  getProfile
+};
+
+export let auth = SlateAuth.create()
+  .output(
+    z.object({
+      token: z.string().describe('Tableau credentials token for API requests'),
+      siteId: z.string().describe('Site LUID returned from sign-in'),
+      userId: z.string().describe('User LUID returned from sign-in'),
+      expiresAt: z
+        .string()
+        .optional()
+        .describe('Estimated ISO timestamp when the Tableau credentials token expires'),
+      authMethod: z
+        .enum(['personal_access_token', 'username_password', 'connected_app_jwt'])
+        .optional()
+        .describe('Authentication method used to obtain the Tableau credentials token')
+    })
+  )
+  .addCustomAuth(personalAccessTokenAuth)
+  .addCustomAuth(usernamePasswordAuth)
+  .addCustomAuth(connectedAppJwtAuth);

package/src/config.ts

@@ -0,0 +1,17 @@
+import { SlateConfig } from 'slates';
+import { z } from 'zod';
+
+export let config = SlateConfig.create(
+  z.object({
+    serverUrl: z
+      .string()
+      .describe('Tableau Server or Tableau Cloud URL (e.g., https://10ay.online.tableau.com)'),
+    siteContentUrl: z
+      .string()
+      .default('')
+      .describe(
+        'Site content URL identifier (e.g., "my-site"). Leave empty for the default site.'
+      ),
+    apiVersion: z.string().default('3.28').describe('Tableau REST API version (e.g., "3.28")')
+  })
+);

package/src/index.ts

@@ -0,0 +1,55 @@
+import { Slate } from 'slates';
+import { spec } from './spec';
+import {
+  listWorkbooks,
+  manageWorkbook,
+  listDatasources,
+  manageDatasource,
+  listViews,
+  getViewData,
+  exportView,
+  manageCustomViews,
+  manageUsers,
+  manageGroups,
+  manageProjects,
+  managePermissions,
+  manageJobs,
+  manageFavorites,
+  manageFlows,
+  manageCollections,
+  manageAlerts,
+  getSiteInfo
+} from './tools';
+import {
+  datasourceEvents,
+  workbookEvents,
+  userEvents,
+  labelEvents,
+  siteEvents,
+  viewEvents
+} from './triggers';
+
+export let provider = Slate.create({
+  spec,
+  tools: [
+    listWorkbooks,
+    manageWorkbook,
+    listDatasources,
+    manageDatasource,
+    listViews,
+    getViewData,
+    exportView,
+    manageCustomViews,
+    manageUsers,
+    manageGroups,
+    manageProjects,
+    managePermissions,
+    manageJobs,
+    manageFavorites,
+    manageFlows,
+    manageCollections,
+    manageAlerts,
+    getSiteInfo
+  ],
+  triggers: [datasourceEvents, workbookEvents, userEvents, labelEvents, siteEvents, viewEvents]
+});