@divyacon/piece-dropbox 0.0.0-stage → 0.1.0

package/src/lib/actions/get-file-link.ts

@@ -0,0 +1,43 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpMethod,
+  AuthenticationType,
+} from '@agnocon/pieces-common';
+import { dropboxAuth } from '../auth';
+
+export const dropboxGetFileLink = createAction({
+  auth: dropboxAuth,
+  name: 'get_dropbox_file_link',
+  description: 'Get a temporary file link',
+  audience: 'both',
+  aiMetadata: { description: 'Returns a temporary, directly downloadable URL for the file at the given Dropbox path. Use when an agent needs a shareable or fetchable link to file contents rather than downloading the bytes into the flow. Read-only lookup; safe to repeat, though the returned URL is short-lived.', idempotent: true },
+  displayName: 'Get temporary file link',
+  props: {
+    path: Property.ShortText({
+      displayName: 'Path',
+      description: 'The path of the file (e.g. /folder1/file.txt)',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const params = {
+      path: context.propsValue.path,
+    };
+
+    const result = await httpClient.sendRequest({
+      method: HttpMethod.POST,
+      url: `https://api.dropboxapi.com/2/files/get_temporary_link`,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: { path: context.propsValue.path },
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: context.auth.access_token,
+      },
+    });
+
+    return result.body;
+  },
+});

package/src/lib/actions/list-a-folder.ts

@@ -0,0 +1,59 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpMethod,
+  AuthenticationType,
+} from '@agnocon/pieces-common';
+import { dropboxAuth } from '../auth';
+
+export const dropboxListAFolder = createAction({
+  auth: dropboxAuth,
+  name: 'list_dropbox_folder',
+  description: 'List the contents of a folder',
+  audience: 'both',
+  aiMetadata: { description: 'Lists the files and subfolders within the given Dropbox folder path (use an empty string for the root), optionally recursing into all subfolders. Use to enumerate folder contents and discover item paths/IDs. Read-only; safe to repeat and returns the same listing for unchanged folders.', idempotent: true },
+  displayName: 'List a folder',
+  props: {
+    path: Property.ShortText({
+      displayName: 'Path',
+      description:
+        'The path of the folder to be listed (e.g. /folder1). Use an empty string for the root folder.',
+      required: true,
+    }),
+    recursive: Property.Checkbox({
+      displayName: 'Recursive',
+      description:
+        'If set to true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders.',
+      defaultValue: false,
+      required: false,
+    }),
+    limit: Property.Number({
+      displayName: 'Limit',
+      description:
+        'The maximum number of results to return (between 1 and 2000). Default is 2000 if not specified.',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = {
+      path: context.propsValue.path,
+      recursive: context.propsValue.recursive,
+      limit: context.propsValue.limit || 2000,
+    };
+
+    const result = await httpClient.sendRequest({
+      method: HttpMethod.POST,
+      url: `https://api.dropboxapi.com/2/files/list_folder`,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: params,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: context.auth.access_token,
+      },
+    });
+
+    return result.body;
+  },
+});

package/src/lib/actions/move-file.ts

@@ -0,0 +1,65 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpMethod,
+  AuthenticationType,
+} from '@agnocon/pieces-common';
+import { dropboxAuth } from '../auth';
+
+export const dropboxMoveFile = createAction({
+  auth: dropboxAuth,
+  name: 'move_dropbox_file',
+  description: 'Move a file',
+  audience: 'both',
+  aiMetadata: { description: 'Moves (or renames) the file at the source path to a new destination path within Dropbox; optionally autorenames on conflict. Use to relocate or rename a single file. Not idempotent: after a successful move the source no longer exists, so repeating the call fails or, with autorename, can produce a differently named copy.', idempotent: false },
+  displayName: 'Move file',
+  props: {
+    from_path: Property.ShortText({
+      displayName: 'From Path',
+      description: 'The current path of the file (e.g. /folder1/oldfile.txt)',
+      required: true,
+    }),
+    to_path: Property.ShortText({
+      displayName: 'To Path',
+      description: 'The new path for the file (e.g. /folder2/newfile.txt)',
+      required: true,
+    }),
+    autorename: Property.Checkbox({
+      displayName: 'Auto Rename',
+      description:
+        "If there's a conflict, have the Dropbox server try to autorename the file to avoid conflict.",
+      defaultValue: false,
+      required: false,
+    }),
+    allow_ownership_transfer: Property.Checkbox({
+      displayName: 'Allow Ownership Transfer',
+      description:
+        'Allows moves by owner even if it would result in an ownership transfer.',
+      defaultValue: false,
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = {
+      from_path: context.propsValue.from_path,
+      to_path: context.propsValue.to_path,
+      autorename: context.propsValue.autorename,
+      allow_ownership_transfer: context.propsValue.allow_ownership_transfer,
+    };
+
+    const result = await httpClient.sendRequest({
+      method: HttpMethod.POST,
+      url: `https://api.dropboxapi.com/2/files/move_v2`,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: params,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: context.auth.access_token,
+      },
+    });
+
+    return result.body;
+  },
+});

package/src/lib/actions/move-folder.ts

@@ -0,0 +1,67 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpMethod,
+  AuthenticationType,
+} from '@agnocon/pieces-common';
+import { dropboxAuth } from '../auth';
+
+export const dropboxMoveFolder = createAction({
+  auth: dropboxAuth,
+  name: 'move_dropbox_folder',
+  description: 'Move a folder',
+  audience: 'both',
+  aiMetadata: { description: 'Moves (or renames) the folder at the source path, including its contents, to a new destination path within Dropbox; optionally autorenames on conflict. Use to relocate or rename an entire directory. Not idempotent: after a successful move the source no longer exists, so repeating the call fails or, with autorename, produces a differently named folder.', idempotent: false },
+  displayName: 'Move folder',
+  props: {
+    from_path: Property.ShortText({
+      displayName: 'From Path',
+      description:
+        'The current path of the folder (e.g. /folder1/sourceFolder)',
+      required: true,
+    }),
+    to_path: Property.ShortText({
+      displayName: 'To Path',
+      description:
+        'The new path for the folder (e.g. /folder2/destinationFolder)',
+      required: true,
+    }),
+    autorename: Property.Checkbox({
+      displayName: 'Auto Rename',
+      description:
+        "If there's a conflict, have the Dropbox server try to autorename the folder to avoid conflict.",
+      defaultValue: false,
+      required: false,
+    }),
+    allow_ownership_transfer: Property.Checkbox({
+      displayName: 'Allow Ownership Transfer',
+      description:
+        'Allows moves by owner even if it would result in an ownership transfer.',
+      defaultValue: false,
+      required: false,
+    }),
+  },
+  async run(context) {
+    const params = {
+      from_path: context.propsValue.from_path,
+      to_path: context.propsValue.to_path,
+      autorename: context.propsValue.autorename,
+      allow_ownership_transfer: context.propsValue.allow_ownership_transfer,
+    };
+
+    const result = await httpClient.sendRequest({
+      method: HttpMethod.POST,
+      url: `https://api.dropboxapi.com/2/files/move_v2`,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: params,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: context.auth.access_token,
+      },
+    });
+
+    return result.body;
+  },
+});

package/src/lib/actions/search.ts

@@ -0,0 +1,117 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpMethod,
+  AuthenticationType,
+} from '@agnocon/pieces-common';
+import { dropboxAuth } from '../auth';
+
+export const dropboxSearch = createAction({
+  auth: dropboxAuth,
+  name: 'search_dropbox',
+  description: 'Search for files and folders',
+  audience: 'both',
+  aiMetadata: { description: 'Searches a Dropbox account for files and folders whose name or content matches a query string (minimum 3 characters), optionally scoped to a path and filtered by file status, extensions, categories, or account. Use to locate items and obtain their paths/IDs before acting on them. Read-only; repeating the same search is safe and returns the same matches.', idempotent: true },
+  displayName: 'Search',
+  props: {
+    query: Property.ShortText({
+      displayName: 'Query',
+      description: 'The search string. Must be at least 3 characters.',
+      required: true,
+    }),
+    path: Property.ShortText({
+      displayName: 'Path',
+      description:
+        'The path to search in. If not specified, the search is performed from the root.',
+      required: false,
+    }),
+    max_results: Property.Number({
+      displayName: 'Max Results',
+      description:
+        'The maximum number of search results to return (up to 1000). Default is 100 if not specified.',
+      required: false,
+    }),
+    order_by: Property.StaticDropdown({
+      displayName: 'Order By',
+      description: 'Specified property of the order of search results.',
+      options: {
+        options: [
+          { label: 'Relevance', value: 'relevance' },
+          { label: 'Modified Time', value: 'modified_time' },
+        ],
+      },
+      defaultValue: 'relevance',
+      required: false,
+    }),
+    file_status: Property.StaticDropdown({
+      displayName: 'File Status',
+      description: 'Restricts search to the given file status.',
+      options: {
+        options: [
+          { label: 'Active', value: 'active' },
+          { label: 'Deleted', value: 'deleted' },
+        ],
+      },
+      defaultValue: 'active',
+      required: false,
+    }),
+    filename_only: Property.Checkbox({
+      displayName: 'Filename Only',
+      description: 'Restricts search to only match on filenames.',
+      defaultValue: false,
+      required: false,
+    }),
+    file_extensions: Property.ShortText({
+      displayName: 'File Extensions',
+      description:
+        'Restricts search to only the extensions specified (comma-separated).',
+      required: false,
+    }),
+    file_categories: Property.ShortText({
+      displayName: 'File Categories',
+      description:
+        'Restricts search to only the file categories specified (comma-separated).',
+      required: false,
+    }),
+    account_id: Property.ShortText({
+      displayName: 'Account ID',
+      description: 'Restricts results to the given account id.',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const options = {
+      path: context.propsValue.path || '',
+      max_results: context.propsValue.max_results || 100,
+      file_status: context.propsValue.file_status,
+      filename_only: context.propsValue.filename_only,
+      file_extensions: context.propsValue.file_extensions
+        ? context.propsValue.file_extensions.split(',')
+        : undefined,
+      file_categories: context.propsValue.file_categories
+        ? context.propsValue.file_categories.split(',')
+        : undefined,
+      account_id: context.propsValue.account_id,
+    };
+
+    const requestBody = {
+      query: context.propsValue.query,
+      options: options,
+    };
+
+    const result = await httpClient.sendRequest({
+      method: HttpMethod.POST,
+      url: `https://api.dropboxapi.com/2/files/search_v2`,
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: requestBody,
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: context.auth.access_token,
+      },
+    });
+
+    return result.body;
+  },
+});

package/src/lib/actions/upload-file.ts

@@ -0,0 +1,79 @@
+import { createAction, Property } from '@agnocon/pieces-framework';
+import {
+  httpClient,
+  HttpMethod,
+  AuthenticationType,
+} from '@agnocon/pieces-common';
+import { dropboxAuth } from '../auth';
+
+export const dropboxUploadFile = createAction({
+  auth: dropboxAuth,
+  name: 'upload_dropbox_file',
+  description: 'Upload a file',
+  audience: 'both',
+  aiMetadata: { description: 'Uploads a file (provided as a URL or base64 file object) to the given Dropbox path in add mode. Use to store binary or arbitrary file content; prefer the create-text-file action when the source is plain text. Not idempotent: each call uploads, so repeating it can create autorenamed duplicates rather than overwriting.', idempotent: false },
+  displayName: 'Upload file',
+  props: {
+    path: Property.ShortText({
+      displayName: 'Path',
+      description:
+        'The path where the file should be saved (e.g. /folder1/file.txt)',
+      required: true,
+    }),
+    file: Property.File({
+      displayName: 'File',
+      description: 'The file URL or base64 to upload',
+      required: true,
+    }),
+    autorename: Property.Checkbox({
+      displayName: 'Auto Rename',
+      description:
+        "If there's a conflict, as determined by mode, have the Dropbox server try to autorename the file to avoid conflict.",
+      defaultValue: false,
+      required: false,
+    }),
+    mute: Property.Checkbox({
+      displayName: 'Mute',
+      description:
+        "Normally, users are made aware of any file modifications in their Dropbox account via notifications in the client software. If true, this tells the clients that this modification shouldn't result in a user notification.",
+      required: false,
+    }),
+    strict_conflict: Property.Checkbox({
+      displayName: 'Strict conflict',
+      description:
+        'Be more strict about how each WriteMode detects conflict. For example, always return a conflict error when mode = WriteMode.update and the given "rev" doesn\'t match the existing file\'s "rev", even if the existing file has been deleted.',
+      required: false,
+    }),
+  },
+  async run(context) {
+    const fileData = context.propsValue.file;
+
+    const params = {
+      autorename: context.propsValue.autorename,
+      path: context.propsValue.path,
+      mode: 'add',
+      mute: context.propsValue.mute,
+      strict_conflict: context.propsValue.strict_conflict,
+    };
+
+    const fileBuffer = Buffer.from(fileData.base64, 'base64');
+    // For information about Dropbox JSON encoding, see https://www.dropbox.com/developers/reference/json-encoding
+    const dropboxApiArg = JSON.stringify(params).replace(/[\u007f-\uffff]/g, (c) => '\\u'+('000'+c.charCodeAt(0).toString(16)).slice(-4));
+
+    const result = await httpClient.sendRequest({
+      method: HttpMethod.POST,
+      url: `https://content.dropboxapi.com/2/files/upload`,
+      body: fileBuffer,
+      headers: {
+        'Dropbox-API-Arg': dropboxApiArg,
+        'Content-Type': 'application/octet-stream',
+      },
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: context.auth.access_token,
+      },
+    });
+
+    return result.body;
+  },
+});

package/src/lib/auth.ts

@@ -0,0 +1,16 @@
+import { PieceAuth } from '@agnocon/pieces-framework';
+
+export const dropboxAuth = PieceAuth.OAuth2({
+  description: '',
+  authUrl: 'https://www.dropbox.com/oauth2/authorize',
+  tokenUrl: 'https://api.dropboxapi.com/oauth2/token',
+  required: true,
+  // include token_access_type=offline as a parameter on Authorization URL in order to return a refresh_token
+  extra: { token_access_type: 'offline' },
+  scope: [
+    'files.metadata.write',
+    'files.metadata.read',
+    'files.content.write',
+    'files.content.read',
+  ],
+});

package/src/lib/triggers/new-folder.ts

@@ -0,0 +1,167 @@
+import {
+  createTrigger,
+  Property,
+  TriggerStrategy,
+} from '@agnocon/pieces-framework';
+
+import {
+  AuthenticationType,
+  HttpMethod,
+  httpClient,
+} from '@agnocon/pieces-common';
+import { dropboxAuth } from '../auth';
+
+type DropboxListFolderEntry = {
+  id: string;
+  name: string;
+  path_lower?: string;
+  path_display?: string;
+  ['.tag']: string;
+};
+
+type DropboxListFolderResponse = {
+  entries: DropboxListFolderEntry[];
+  cursor: string;
+  has_more: boolean;
+};
+
+// Returns the latest cursor for a folder without fetching any entries.
+// Designed for apps that only need to know about new changes going forward.
+const getLatestCursor = async (
+  accessToken: string,
+  path: string,
+  recursive: boolean,
+): Promise<string> => {
+  const res = await httpClient.sendRequest<{ cursor: string }>({
+    method: HttpMethod.POST,
+    url: 'https://api.dropboxapi.com/2/files/list_folder/get_latest_cursor',
+    headers: { 'Content-Type': 'application/json' },
+    body: { path, recursive, include_deleted: false },
+    authentication: {
+      type: AuthenticationType.BEARER_TOKEN,
+      token: accessToken,
+    },
+  });
+  return res.body.cursor;
+};
+
+// Calls list_folder/continue with a stored cursor and returns all new folder entries,
+// plus the updated cursor to store for the next poll.
+const getChangedFolders = async (
+  accessToken: string,
+  cursor: string,
+): Promise<{ folders: DropboxListFolderEntry[]; newCursor: string }> => {
+  const folders: DropboxListFolderEntry[] = [];
+  let currentCursor = cursor;
+  let hasMore = true;
+
+  while (hasMore) {
+    const res = await httpClient.sendRequest<DropboxListFolderResponse>({
+      method: HttpMethod.POST,
+      url: 'https://api.dropboxapi.com/2/files/list_folder/continue',
+      headers: { 'Content-Type': 'application/json' },
+      body: { cursor: currentCursor },
+      authentication: {
+        type: AuthenticationType.BEARER_TOKEN,
+        token: accessToken,
+      },
+    });
+
+    const newFolders = res.body.entries.filter((e) => e['.tag'] === 'folder');
+    folders.push(...newFolders);
+    currentCursor = res.body.cursor;
+    hasMore = res.body.has_more;
+  }
+
+  return { folders, newCursor: currentCursor };
+};
+
+// Fetches recent folder entries for test mode — returns up to 5.
+const listRecentFolders = async (
+  accessToken: string,
+  path: string,
+  recursive: boolean,
+): Promise<DropboxListFolderEntry[]> => {
+  const res = await httpClient.sendRequest<DropboxListFolderResponse>({
+    method: HttpMethod.POST,
+    url: 'https://api.dropboxapi.com/2/files/list_folder',
+    headers: { 'Content-Type': 'application/json' },
+    body: { path, recursive, include_deleted: false, limit: 100 },
+    authentication: {
+      type: AuthenticationType.BEARER_TOKEN,
+      token: accessToken,
+    },
+  });
+
+  return res.body.entries.filter((e) => e['.tag'] === 'folder').slice(0, 5);
+};
+
+export const dropboxNewFolder = createTrigger({
+  auth: dropboxAuth,
+  name: 'new_folder',
+  displayName: 'New Folder',
+  description:
+    'Triggers when a new folder is created inside a watched Dropbox folder.',
+  aiMetadata: {
+    description: 'Fires when a new folder appears inside the watched Dropbox folder path, detected by polling the folder for changes since the last cursor. Each fired event represents one newly created folder; enable recursive watching to also detect folders created within subfolders.',
+  },
+
+  type: TriggerStrategy.POLLING,
+
+  props: {
+    path: Property.ShortText({
+      displayName: 'Watched Folder Path',
+      description: 'Folder path to watch. Use empty string "" for root.',
+      required: true,
+      defaultValue: '',
+    }),
+
+    recursive: Property.Checkbox({
+      displayName: 'Recursive',
+      description: 'Watch subfolders recursively. May return many results.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+
+  sampleData: {
+    '.tag': 'folder',
+    name: 'Project Docs',
+    id: 'id:a4ayc_80_OEAAAAAAAAAXw',
+    path_display: '/Work/Project Docs',
+    path_lower: '/work/project docs',
+  },
+
+  onEnable: async (context) => {
+    const cursor = await getLatestCursor(
+      context.auth.access_token,
+      context.propsValue.path || '',
+      context.propsValue.recursive ?? false,
+    );
+    await context.store.put('cursor', cursor);
+  },
+
+  onDisable: async (context) => {
+    await context.store.delete('cursor');
+  },
+
+  run: async (context) => {
+    const cursor = await context.store.get<string>('cursor');
+    if (!cursor) return [];
+
+    const { folders, newCursor } = await getChangedFolders(
+      context.auth.access_token,
+      cursor,
+    );
+    await context.store.put('cursor', newCursor);
+    return folders;
+  },
+
+  test: async (context) => {
+    return listRecentFolders(
+      context.auth.access_token,
+      context.propsValue.path || '',
+      context.propsValue.recursive ?? false,
+    );
+  },
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.