@smapiot/piral-cloud-node 0.12.2 → 0.12.3-pre.20220810.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 smapiot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+[![Piral Logo](https://github.com/smapiot/piral/raw/main/docs/assets/logo.png)](https://piral.io)
+
+# `@smapiot/piral-cloud-node`
+
+Node-usable API Client for the [Piral Feed Service](https://www.piral.cloud).
+
+This package is compatible with Node.js v12 or higher.
+
+## Important Links
+
+* 📢 **[We are hiring!](https://smapiot.com/jobs)** - work with us on Piral, its ecosystem and our users
+* 🌍 [Website](https://www.piral.cloud/) - learn more about the Piral Feed Service
+* 📖 [Documentation](https://docs.piral.cloud/) - everything to get started and master the Piral Feed Service
+* 👪 [Community Chat](https://gitter.im/piral-io/community) - ask questions and provide answers in our Gitter room
+
+## Installation
+
+The package can be installed with your favorite npm client, e.g.:
+
+```sh
+npm i @smapiot/piral-cloud-node
+```
+
+Once installed the package is ready to be used.
+
+## Usage
+
+To use the package you need to import the `createServiceClient` function and call it:
+
+```js
+const { createServiceClient } = require('@smapiot/piral-cloud-node');
+
+const client = createServiceClient({
+  apiKey: '123...',
+});
+
+// use the client
+```
+
+If you want to use it with your own Piral Feed Service instance then provide the `host` option:
+
+```js
+const { createServiceClient } = require('@smapiot/piral-cloud-node');
+
+const client = createServiceClient({
+  apiKey: '123...',
+  host: 'http://localhost:9000',
+});
+
+// use the client
+```
+
+## Example
+
+If you want to just manipulate a feed you can go ahead and use the `doUpdateFeed` function.
+
+```js
+const { createServiceClient } = require('@smapiot/piral-cloud-node');
+
+const client = createServiceClient({
+  apiKey: '123...',
+});
+
+const feedId = 'my-feed';
+
+console.log('Before', await client.doQueryFeed(feedId));
+
+await client.doUpdateFeed(feedId, {
+  contributors: ['a@b.com', 'c@d.com'],
+});
+
+console.log('After', await client.doQueryFeed(feedId));
+```
+
+Everything is fully typed using TypeScript declarations.
+
+## License
+
+This SDK is released using the MIT license. For more information see the [license file](./LICENSE).

package/lib/index.d.ts

@@ -1,21 +1,4 @@
 declare module "@smapiot/piral-cloud-node" {
-  /**
-   * The options for creating a new service client.
-   */
-  export interface CreateServiceClientOptions {
-    /**
-     * Defines the host to talk to. Set this if you want to communicate
-     * with your own feed service instance.
-     * @default https://feed.piral.cloud
-     */
-    host?: string;
-    /**
-     * Defines the API key to use for making the HTTP calls. Needs
-     * to be provided.
-     */
-    apiKey: string;
-  }
-
   /**
    * Creates a new service client for use in Node.js-based applications.
    * @param options The options for creating the client.
@@ -23,6 +6,11 @@ declare module "@smapiot/piral-cloud-node" {
    */
   export function createServiceClient(options: CreateServiceClientOptions): FeedServiceApiClient;
 
+  /**
+   * The options for creating a new service client.
+   */
+  export type CreateServiceClientOptions = CreateServiceClientBaseOptions & CreateServiceClientApiKeyOptions;
+
   export class FeedServiceApiClient {
     constructor(private http: FetchClient, host?: string);
     getUrl(path: string): string;
@@ -105,6 +93,23 @@ declare module "@smapiot/piral-cloud-node" {
     doDownloadFile(fileUrl: string, ac?: AbortController): Promise<Blob>;
   }
 
+  /**
+   * The basic / core options for creating a new service client.
+   */
+  export interface CreateServiceClientBaseOptions {
+    /**
+     * Defines the host to talk to. Set this if you want to communicate
+     * with your own feed service instance.
+     * @default https://feed.piral.cloud
+     */
+    host?: string;
+  }
+
+  /**
+   * The API key options for creating a new service client.
+   */
+  export type CreateServiceClientApiKeyOptions = CreateServiceClientSimpleApiKeyOptions | CreateServiceClientAdvancedApiKeyOptions;
+
   export interface FetchClient {
     getAuthorizationHeader(): Promise<string>;
     fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
@@ -532,6 +537,32 @@ declare module "@smapiot/piral-cloud-node" {
     }>;
   }
 
+  /**
+   * The simple API key options for creating a new service client.
+   */
+  export interface CreateServiceClientSimpleApiKeyOptions {
+    /**
+     * Defines the API key to use for making the HTTP calls. Needs
+     * to be provided.
+     */
+    apiKey: string;
+  }
+
+  /**
+   * The advanced API key options for creating a new service client.
+   */
+  export interface CreateServiceClientAdvancedApiKeyOptions {
+    /**
+     * Defines the API key to use for making the HTTP calls. Needs
+     * to be provided.
+     */
+    resolveApiKey(): Promise<string>;
+    /**
+     * Defines the type of the resolved API key.
+     */
+    apiKeyType?: "basic" | "bearer" | "none";
+  }
+
   export interface ApiData<T> {
     items: Array<T>;
   }

package/lib/index.js

@@ -5974,6 +5974,39 @@ function fixResponseChunkedTransferBadEnding(request, errorCallback) {
   });
 }
 
+// src/utils.ts
+function createKeyHandler(apiKeyType) {
+  switch (apiKeyType) {
+    case "basic":
+      return (apiKey) => `Basic ${apiKey}`;
+    case "bearer":
+      return (apiKey) => `Bearer ${apiKey}`;
+    default:
+      return (apiKey) => apiKey;
+  }
+}
+function createAuthHead(options) {
+  if ("apiKey" in options) {
+    const { apiKey } = options;
+    if (typeof apiKey !== "string") {
+      throw new Error('The field "apiKey" has to be of type string.');
+    }
+    return () => Promise.resolve(`Basic ${apiKey}`);
+  } else if ("resolveApiKey" in options) {
+    const { resolveApiKey, apiKeyType = "basic" } = options;
+    if (typeof options.resolveApiKey !== "function") {
+      throw new Error('The field "resolveApiKey" has to be of type function.');
+    }
+    if (typeof apiKeyType !== "string") {
+      throw new Error('The field "apiKeyType" has to be of type string.');
+    }
+    const makeKey = createKeyHandler(apiKeyType);
+    return () => resolveApiKey().then(makeKey);
+  } else {
+    throw new Error('You must either specify "apikey" or "resolveApiKey".');
+  }
+}
+
 // src/index.ts
 function createServiceClient(options) {
   if (typeof options === "undefined") {
@@ -5982,20 +6015,16 @@ function createServiceClient(options) {
   if (typeof options !== "object") {
     throw new Error('The "options" have to be an object containing an "apiKey" field.');
   }
-  const { host = "https://feed.piral.cloud", apiKey } = options;
+  const { host = "https://feed.piral.cloud" } = options;
   if (typeof host !== "string") {
     throw new Error('The field "host" has to be of type string.');
   }
-  if (typeof apiKey !== "string") {
-    throw new Error('The field "apiKey" has to be of type string.');
-  }
+  const getAuthorizationHeader = createAuthHead(options);
   const http3 = {
     fetch,
     FormData,
     Headers,
-    getAuthorizationHeader() {
-      return Promise.resolve(apiKey);
-    }
+    getAuthorizationHeader
   };
   return new FeedServiceApiClient(http3, host);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smapiot/piral-cloud-node",
-  "version": "0.12.2",
+  "version": "0.12.3-pre.20220810.2",
   "description": "Piral Cloud: Node-usable API Client for the Piral Feed Service.",
   "author": {
     "name": "smapiot",
@@ -40,7 +40,7 @@
     "node"
   ],
   "devDependencies": {
-    "@piral/feed-client": "^0.12.2",
+    "@piral/feed-client": "^0.12.3",
     "dets": "^0.12.0",
     "esbuild": "^0.14.51",
     "node-fetch": "^3.2.10"