@flink-app/contentone-plugin 0.12.1-alpha.4 → 0.12.1-alpha.40

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@flink-app/contentone-plugin",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.40",
     "description": "Flink plugin that enables easy to use communication with content one",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
-        "prepublish": "tsc"
+        "prepare": "tsc"
     },
     "author": "johan@frost.se",
     "publishConfig": {
@@ -18,11 +18,11 @@
         "got": "^9.6.0"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.40",
         "@types/got": "^9.6.0",
         "@types/node": "22.13.10",
         "ts-node": "^9.1.1",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "456502f273fe9473df05b71a803f3eda1a2f8931"
 }

package/readme.md

@@ -1,244 +1,498 @@
-# Flink API Docs
+# @flink-app/contentone-plugin
 
-A FLINK plugin that makes it easy to consume data from Content One.
+A Flink plugin for integrating with Content One CMS (Aquro). This plugin provides a simple and type-safe way to consume content from Content One collections, execute management actions, and upload files to the Content One CDN.
 
-The plugin also makes it possible to call ContentOne actions.
+## Features
 
-## Installation
+- Retrieve documents from Content One collections
+- List and query collection documents with filtering and pagination
+- Execute Content One management actions
+- Upload files to Content One CDN with image processing options
+- Support for multiple collections and CDN configurations
+- Environment switching (Production/Staging)
+- Document relation resolution
+- Language-specific content retrieval
+- Full TypeScript support with generic types
+- Direct API calls without pre-configuration
 
-Install plugin to your flink app project:
+## Installation
 
-```
-npm i -S @flink-app/contentone-plugin
+```bash
+npm install @flink-app/contentone-plugin
 ```
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+## Usage
 
-```
-import { ContentOneClient, ContentOneManagementAction, contentOnePlugin } from "@flink-app/contentone-plugin"
+### Basic Setup
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import {
+  contentOnePlugin,
+  ContentOneClient,
+  ContentOneManagementAction,
+  ContentOneCDN,
+} from "@flink-app/contentone-plugin";
 
 function start() {
   new FlinkApp<AppContext>({
     name: "My app",
     plugins: [
-        // Register plugin
       contentOnePlugin({
-        collections : {
-          "Collection1" : new ContentOneClient({
-              collection : "collectionid",
-              token : "token.."
+        collections: {
+          NewsItems: new ContentOneClient({
+            collection: "collection_id_here",
+            token: "your_token_here",
+          }),
+          Products: new ContentOneClient({
+            collection: "another_collection_id",
+            token: "your_token_here",
           }),
-          "Collection2" : new ContentOneClient({
-              collection : "collectionid",
-              token : "token.."
-          })
         },
-        actions : {
-          "action1" : new ContentOneManagementAction({
-            actionId : "action1",
-            apiKey : "apikey"
-          })
+        actions: {
+          SendEmail: new ContentOneManagementAction({
+            actionId: "send_email_action_id",
+            apiKey: "your_api_key_here",
+          }),
         },
-        cdns : {
-          "photos" : new ContentOneCDN({
-            token : "file_archive_token"
-          })
-        }
-
-      })
+        cdns: {
+          photos: new ContentOneCDN({
+            token: "file_archive_token",
+          }),
+        },
+        baseUrl: "https://cdb.aquro.com", // optional
+        managementBaseUrl: "https://api-cm.aquro.com", // optional
+      }),
     ],
   }).start();
 }
-
 ```
 
-Finally add plugin context type as generic argument to your application context (probable the `Ctx.ts` in root project)
+### Add Plugin Context to Your Application
 
-```
+```typescript
 import { contentOnePluginContext } from "@flink-app/contentone-plugin";
 
-export interface Ctx extends FlinkContext<contentOnePluginContext> {
-  repos: {};
+export interface AppContext extends FlinkContext<contentOnePluginContext> {
+  repos: {
+    // your repos
+  };
 }
-
 ```
 
-## Collections
+## Configuration Options
 
-Collections can be called for `get`,`list` and `query` actions.
+- `collections` (optional): Object mapping collection names to `ContentOneClient` instances
+- `actions` (optional): Object mapping action names to `ContentOneManagementAction` instances
+- `cdns` (optional): Object mapping CDN names to `ContentOneCDN` instances
+- `baseUrl` (optional): Content One API base URL (defaults to `https://cdb.aquro.com`)
+- `managementBaseUrl` (optional): Content One Management API base URL (defaults to `https://api-cm.aquro.com`)
 
-### get
+## Working with Collections
 
-```
-const document  = (await ctx.plugins.contentOne.collections.NewsItems.get("documentid")).document
-```
+### Get a Single Document
 
-The following optional options can also be specified:
+```typescript
+const document = (await ctx.plugins.contentOne.collections.NewsItems.get("document_id")).document;
+```
 
-| Options     | Description                                       |
-| ----------- | ------------------------------------------------- | ---------------------------------- |
-| language    | Language code (ISO 639-1) to get the documents in |
-| environment | "Production"                                      | "Staging",                         |
-| resolve     | "yes"                                             | "no" - Resolving related documents |
+With options:
 
-```
-const document  = (await ctx.plugins.contentOne.collections.NewsItems.get("documentid"), { language : "en" }).document
+```typescript
+const document = (
+  await ctx.plugins.contentOne.collections.NewsItems.get("document_id", {
+    language: "en",
+    environment: "Production",
+    resolve: "yes",
+  })
+).document;
 ```
 
-### list
+### List Documents
 
+```typescript
+const documents = (await ctx.plugins.contentOne.collections.NewsItems.list()).documents;
 ```
-const documents  = (await ctx.plugins.contentOne.collections.NewsItems.list()).documents
+
+With pagination and sorting:
+
+```typescript
+const documents = (
+  await ctx.plugins.contentOne.collections.NewsItems.list({
+    skip: 0,
+    limit: 50,
+    sort: "createdDate",
+    sort_direction: "desc",
+    language: "en",
+    environment: "Production",
+    resolve: "yes",
+  })
+).documents;
 ```
 
-The following optional options can also be specified:
+### Query Documents
 
-| Options        | Description                                       |
-| -------------- | ------------------------------------------------- | ---------------------------------- |
-| language       | Language code (ISO 639-1) to get the documents in |
-| environment    | "Production"                                      | "Staging",                         |
-| resolve        | "yes"                                             | "no" - Resolving related documents |
-| skip           | Skip a number of documents, defaults to 0         |
-| limit          | Maximum of documents returned, defaults to 10 000 |
-| sort           | Field to sort the documents by                    |
-| sort_direction | "asc"                                             | "desc"                             |
+Execute a named query with arguments:
 
-```
-const document  = (await ctx.plugins.contentOne.collections.NewsItems.get("documentid"), { skip : 100 }).document
+```typescript
+const documents = (
+  await ctx.plugins.contentOne.collections.NewsItems.query("GetNewsByCategory", {
+    category: "Technology",
+  })
+).documents;
 ```
 
-### query
+With options:
 
-```
-const documents  = (await ctx.plugins.contentOne.collections.NewsItems.query("QueryName", { Arg : "Hello" })).documents
+```typescript
+const documents = (
+  await ctx.plugins.contentOne.collections.NewsItems.query(
+    "GetNewsByCategory",
+    {
+      category: "Technology",
+    },
+    {
+      limit: 20,
+      sort: "publishDate",
+      sort_direction: "desc",
+    }
+  )
+).documents;
 ```
 
-The following optional options can also be specified:
+## Request Options
 
-| Options        | Description                                       |
-| -------------- | ------------------------------------------------- | ---------------------------------- |
-| language       | Language code (ISO 639-1) to get the documents in |
-| environment    | "Production"                                      | "Staging",                         |
-| resolve        | "yes"                                             | "no" - Resolving related documents |
-| skip           | Skip a number of documents, defaults to 0         |
-| limit          | Maximum of documents returned, defaults to 10 000 |
-| sort           | Field to sort the documents by                    |
-| sort_direction | "asc"                                             | "desc"                             |
+### Common Options
 
-```
-const documents  = (await ctx.plugins.contentOne.collections.NewsItems.query("QueryName", { Arg : "Hello" }, { limit : 1000 })).documents
-```
+Available for `get`, `list`, and `query`:
 
-## Actions
+- `language` (string): Language code (ISO 639-1) to retrieve documents in (e.g., "en", "sv")
+- `environment` ("Production" | "Staging"): Which environment to fetch from
+- `resolve` ("yes" | "no"): Whether to resolve related documents
 
-Content One actions can easily be called;
+### List and Query Options
 
-```
-const resp =  ctx.plugins.contentOne.actions.ActionName.execute({ Arg : "Hello" });
-```
+Additional options for `list` and `query`:
 
-## Files
+- `skip` (number): Number of documents to skip (default: 0)
+- `limit` (number): Maximum documents to return (default: 10,000)
+- `sort` (string): Field name to sort by
+- `sort_direction` ("asc" | "desc"): Sort direction
 
-Content One have a built in File Archive and with this plugin you might easily upload files:
+## TypeScript Type Safety
 
-First configure your cdn:connections on plugin initilization. Then simply call the upload function:
+Use generic types to get typed document responses:
 
-```
-const resp = await ctx.plugins.contentOne.cdns.photos.upload("/tmp/file.png", {} )
+```typescript
+interface NewsItem {
+  _id: string;
+  title: string;
+  content: string;
+  publishDate: string;
+  category: string;
+}
 
+// Single document
+const document = (
+  await ctx.plugins.contentOne.collections.NewsItems.get<NewsItem>("document_id")
+).document;
+// document is typed as NewsItem
+
+// Multiple documents
+const documents = (
+  await ctx.plugins.contentOne.collections.NewsItems.list<NewsItem>()
+).documents;
+// documents is typed as NewsItem[]
 ```
 
-The following options can be specified
+## Management Actions
 
-#### folderId
+### Execute Pre-configured Actions
 
-Folter to save the file to. Normally leave empty and default folder for the token will be used.
+```typescript
+const response = await ctx.plugins.contentOne.actions.SendEmail.execute({
+  to: "user@example.com",
+  subject: "Hello",
+  body: "Welcome to our service",
+});
 
-#### image_rotate
+if (response.status === "success") {
+  console.log("Email sent:", response.data);
+}
+```
 
-Set to 90,180,270 or auto to rotate the image, normally set it to auto and the image will be rotated based on the exif data of the image.
+### Execute Actions Directly
 
-#### image_resize_width
+Without pre-configuration:
 
-Specify a width if you like to resize the image to a specific width
+```typescript
+const response = await ctx.plugins.contentOne.management.action(
+  "action_id",
+  "api_key",
+  {
+    arg1: "value1",
+    arg2: "value2",
+  }
+);
+```
 
-#### image_resize_height
+### Typed Action Responses
 
-Specify a height if you like to resize the image to a specific height
+```typescript
+interface EmailResponse {
+  messageId: string;
+  status: string;
+}
 
-#### image_resize_max
+const response = await ctx.plugins.contentOne.actions.SendEmail.execute<EmailResponse>({
+  to: "user@example.com",
+  subject: "Hello",
+});
 
-If set to "yes" the image will be as big as possible, but never bigger then the specified width and height (and still keeping the aspect ratio)
+if (response.status === "success") {
+  console.log("Message ID:", response.data.messageId);
+}
+```
 
-#### image_resize_crop
+## File Upload (CDN)
 
-Make the size of the resized image exacly the specified size, and crop image if required.
+### Upload Files with Pre-configured CDN
 
-#### image_thumb
+```typescript
+const result = await ctx.plugins.contentOne.cdns.photos.upload("/tmp/photo.jpg", {
+  image_rotate: "auto",
+  image_resize_width: 1200,
+  image_resize_max: "yes",
+  image_thumb: "yes",
+  image_thumb_width: 200,
+  image_thumb_height: 200,
+});
 
-Set to yes to also generate a thumbnail
+if (result.status === "success") {
+  console.log("File URL:", result.file.Url);
+  console.log("Thumbnail URL:", result.file.Thumbnail);
+}
+```
 
-#### image_thumb_width
+### Upload Files Directly
 
-Specify width of thumbnail
+Without pre-configuration:
 
-#### image_thumb_height
+```typescript
+const result = await ctx.plugins.contentOne.cdnClient.upload("/tmp/photo.jpg", "file_archive_token", {
+  image_rotate: "auto",
+  image_resize_width: 1200,
+});
+```
 
-Specify height of thumbnail
+### Upload Options
 
-### Response
+- `folderId` (string): Folder to save the file to
+- `image_rotate` ("90" | "180" | "270" | "auto"): Rotate image (auto uses EXIF data)
+- `image_resize_width` (number): Resize to specific width
+- `image_resize_height` (number): Resize to specific height
+- `image_resize_max` ("yes" | "no"): Keep aspect ratio, fit within dimensions
+- `image_resize_crop` ("center" | "attention"): Crop strategy for exact dimensions
+- `image_thumb` ("yes" | "no"): Generate thumbnail
+- `image_thumb_width` (number): Thumbnail width
+- `image_thumb_height` (number): Thumbnail height
 
-When uploading a file you will get a response back looking something like this:
+### Upload Response
 
-```
+```typescript
 {
-  status: 'success',
+  status: "success" | "fail",
   file: {
-    _id: '60e461887be82613ad95b39c',
-    ProjectID: '5a980fb80459493b3378c9a2',
-    Local_FileName: 'watermark.png',
-    CDN_FileName: 'ef32c174d9c94caf8d5490626d62952a.png',
-    Url: 'https://aqurocm.blob.core.windows.net/5a980fb80459493b3378c9a2-f7dd9134781541f6adacbdd654091847/ef32c174d9c94caf8d5490626d62952a.png',
-    Type: 'Image',
-    Size: 26888,
-    CreatedDate: '2021-07-06T13:58:32.920Z',
-    Thumbnail: 'https://aqurocm.blob.core.windows.net/5a980fb80459493b3378c9a2-f7dd9134781541f6adacbdd654091847/db275bd42fe345499fded27a66bf59ce.png',
-    ThumbnailCDN_Filename: 'db275bd42fe345499fded27a66bf59ce.png',
-    FolderID: '5a9811ac0459493b3378c9b6'
+    _id: string;
+    ProjectID: string;
+    Local_FileName: string;
+    CDN_FileName: string;
+    Url: string;
+    Type: string;
+    Size: number;
+    CreatedDate: string;
+    FolderID: string;
+    Thumbnail?: string;
+    ThumbnailCDN_Filename?: string;
   }
 }
 ```
 
-## Direct collection calls
+## Direct API Calls
 
-Direct calls to a collection can be made without configured by the initializing code. To do this use the getClient method:
+The plugin supports direct API calls without pre-configuration:
 
+### Direct Collection Access
+
+```typescript
+const document = (
+  await ctx.plugins.contentOne.getClient({
+    token: "token",
+    collection: "collection_id",
+  }).get("document_id")
+).document;
 ```
-const document  = (await ctx.plugins.contentOne.getClient({ token : "token", "collection" : "collectionid"}).get("documentid")).document
-```
 
-## Direct action calls
+### Direct Action Execution
+
+```typescript
+const response = await ctx.plugins.contentOne.management.action(
+  "action_id",
+  "api_key",
+  {
+    argument: "value",
+  }
+);
+```
 
-Direct calls to a actions can be made without configured by the initializing code. To do this use the management.action method:
+### Direct CDN Upload
 
+```typescript
+const result = await ctx.plugins.contentOne.cdnClient.upload(
+  "./file.txt",
+  "token",
+  {}
+);
 ```
-const resp = (await ctx.plugins.contentOne.management.action("actionid", "apikey", {})).data;
+
+## Complete Example
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import {
+  contentOnePlugin,
+  ContentOneClient,
+  ContentOneManagementAction,
+  ContentOneCDN,
+} from "@flink-app/contentone-plugin";
+
+interface Article {
+  _id: string;
+  title: string;
+  content: string;
+  author: string;
+  publishedAt: string;
+}
+
+const plugin = contentOnePlugin({
+  collections: {
+    Articles: new ContentOneClient({
+      collection: "articles_collection_id",
+      token: process.env.CONTENTONE_TOKEN!,
+      debug: true, // Enable logging
+    }),
+  },
+  actions: {
+    PublishArticle: new ContentOneManagementAction({
+      actionId: "publish_article",
+      apiKey: process.env.CONTENTONE_API_KEY!,
+    }),
+  },
+  cdns: {
+    images: new ContentOneCDN({
+      token: process.env.CONTENTONE_CDN_TOKEN!,
+    }),
+  },
+});
+
+// Later in your handler or job:
+async function publishArticle(ctx: AppContext, articleId: string) {
+  // Get the article
+  const article = (
+    await ctx.plugins.contentOne.collections.Articles.get<Article>(articleId, {
+      language: "en",
+      environment: "Production",
+    })
+  ).document;
+
+  // Execute publish action
+  const result = await ctx.plugins.contentOne.actions.PublishArticle.execute({
+    articleId: article._id,
+    publishDate: new Date().toISOString(),
+  });
+
+  return result;
+}
+
+async function uploadArticleImage(ctx: AppContext, imagePath: string) {
+  const upload = await ctx.plugins.contentOne.cdns.images.upload(imagePath, {
+    image_rotate: "auto",
+    image_resize_width: 1200,
+    image_resize_max: "yes",
+    image_thumb: "yes",
+    image_thumb_width: 300,
+    image_thumb_height: 200,
+  });
+
+  if (upload.status === "success") {
+    return {
+      imageUrl: upload.file.Url,
+      thumbnailUrl: upload.file.Thumbnail,
+    };
+  }
+
+  throw new Error("Upload failed");
+}
 ```
 
-## Direct CDN calls
+## Error Handling
 
-Direct calls to a CDN client can also be made without configuring it first:
+Always wrap API calls in try-catch blocks:
 
+```typescript
+try {
+  const document = (
+    await ctx.plugins.contentOne.collections.NewsItems.get("document_id")
+  ).document;
+} catch (error) {
+  console.error("Failed to fetch document:", error);
+  // Handle error appropriately
+}
 ```
-const resp  = await ctx.plugins.contentOne.cdns.photos.upload("./file.txt", "token", { })
+
+## Debug Mode
+
+Enable debug mode for a collection to log all API requests and responses:
+
+```typescript
+new ContentOneClient({
+  collection: "collection_id",
+  token: "token",
+  debug: true, // Logs all requests and responses
+});
 ```
 
-## Typed calls
+## API Response Types
 
-Each of these calls can specify the type on the returned document or documents by setting the type as a generic argument.
+### Document Response
 
+```typescript
+{
+  status: "success" | "error",
+  document: T,
+  message?: string
+}
 ```
-const document  = (await ctx.plugins.contentOne.collections.NewsItems.get<Type>("documentid")).document
 
+### Document List Response
 
+```typescript
+{
+  status: "success" | "error",
+  documents: T[],
+  message?: string
+}
+```
+
+### Action Response
+
+```typescript
+{
+  status: "success" | "error",
+  data: T
+}
 ```
+
+## License
+
+MIT