Merge pull request #1367 from datopian/feat/ckan-api-client-js

ckan-api-client-js

Author: demenech

.changeset/lemon-ducks-shake.md

@@ -0,0 +1,5 @@
+---
+'@portaljs/ckan-api-client-js': minor
+---
+
+Initial public release

package-lock.json

@@ -0,0 +1,44 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# database
+/prisma/db.sqlite
+/prisma/db.sqlite-journal
+
+# next.js
+/.next/
+/out/
+next-env.d.ts
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# local env files
+# do not commit any .env files to git, except for the .env.example file. https://create.t3.gg/en/usage/env-variables#using-environment-variables
+.env
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+
+/dist

packages/ckan-api-client-js/.gitignore

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json.schemastore.org/mocharc.json",
+  "require": "tsx",
+  "spec": ["test/**/*.ts"]
+}

packages/ckan-api-client-js/.mocharc.json

@@ -0,0 +1,43 @@
+# @portaljs/ckan-api-client-js
+
+## 1.3.3
+
+### Patch Changes
+
+- 3bb69b4: Dual build as ES module and CommonJS so that exports work properly on Next.js builds
+
+## 1.3.2
+
+### Patch Changes
+
+- 1bc2193: Export CkanRequest as default export and CkanRequestError as named export
+
+## 1.3.1
+
+### Patch Changes
+
+- be275c4: CkanRequestError custom error wasn't being exported
+
+## 1.3.0
+
+### Minor Changes
+
+- b1a75f2: Post and get methods are now generic, so that response can be properly typed"
+
+## 1.2.1
+
+### Patch Changes
+
+- 6a4eafe: Fix get and post method being exported without types
+
+## 1.2.0
+
+### Minor Changes
+
+- 9ab2d02: Implemented apiKey and formData options
+
+## 1.1.0
+
+### Minor Changes
+
+- dde4357: Add support to Authorization Error

packages/ckan-api-client-js/CHANGELOG.md

@@ -0,0 +1,91 @@
+## CKAN API client - JavaScript
+
+Among other JS clients publicly available, the objectives of this one are:
+
+- **To be completely flexible in terms of which CKAN actions are supported**, so users specify which action should be called by its name rather than my importing and calling a method implemented specifically for the given action. This ensure that all core and custom actions are supported, including all possible parameters.
+- **To reduce repetition when calling CKAN actions**, by reading global configurations on environemnt variables (such as the CKAN URL) and having common configurations by default (e.g. all requests by default will have the "content-type" header set to "application/json", avoiding that requests are sent without it and avoing that this has to be repeated everywhere).
+- **To properly handle errors**, by properly detecting when an error happened and throwing an error with a useful message that can be shown to the final users.
+- **To expose the underlying request properties**, so that anything can be customized e.g. headers
+
+_**NOTE:**_ developed mainly to be used on Next.js projects.
+
+## Usage
+
+Install the package on the project with (or `npm link` for local development):
+
+```
+npm i @portaljs/ckan-api-client-js
+```
+
+Set the following environment variables on your project:
+
+```bash
+NEXT_PUBLIC_CKAN_URL=http://ckan.com # <= This should be updated
+```
+
+Import the client with:
+
+```javascript
+import CkanRequest from "ckan-api-client-js";
+```
+
+### Methods
+
+`CkanRequest` exports 2 main methods:
+
+- `CkanRequest.get("action_name", options)`
+- `CkanRequest.post("action_name", options)`
+
+`options` may have the following properties:
+
+- `apiKey` - CKAN API key for authorization
+- `headers` - Request headers. E.g. `{ "Authorization": "api_token" }`
+- `json` - JSON body for POST requests. E.g. `{ "id": "123" }`
+- `formData` - formData for POST requests
+
+### Examples
+
+#### `package_show`
+
+```javascript
+const dataset = await CkanRequest.get(
+    "package_show?id=123",
+    {
+        apiKey: "my-token"
+    }
+);
+```
+
+#### `package_patch`
+
+```javascript
+const dataset = await CkanRequest.post(
+    "package_patch",
+    {
+        headers: {
+            Authorization: "apikey",
+        },
+        json: { "id": "123", "title": "My new title" },
+    }
+);
+```
+
+#### Error handling
+
+If an exception happens, simply catch that and show its message to the user. Example:
+
+```javascript
+try {
+    const dataset = CkanRequest.get("package_show?id=123")
+} catch (e) {
+    alert(e.message) // E.g. "Dataset not found"
+}
+
+```
+
+## Development
+
+Currently, `npm link` is being used for development purposes.
+
+To do so, simply build (`npm run build`) the project and then link it (`npm link ...`) on another project to test changes.
+