{"id":18510114,"url":"https://github.com/gitana/cloudcms-javascript-driver","last_synced_at":"2025-04-09T04:33:06.687Z","repository":{"id":49258772,"uuid":"205239830","full_name":"gitana/cloudcms-javascript-driver","owner":"gitana","description":"Updated Cloud CMS JS Driver using modern ECMAScript and Promises","archived":false,"fork":false,"pushed_at":"2024-02-13T15:51:39.000Z","size":7477,"stargazers_count":2,"open_issues_count":3,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-14T09:04:10.939Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gitana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-29T19:51:39.000Z","updated_at":"2024-04-30T21:45:02.941Z","dependencies_parsed_at":"2022-09-18T10:41:12.749Z","dependency_job_id":"6d534176-ffa0-4643-9330-bb233da53e6b","html_url":"https://github.com/gitana/cloudcms-javascript-driver","commit_stats":{"total_commits":89,"total_committers":6,"mean_commits":"14.833333333333334","dds":0.2808988764044944,"last_synced_commit":"0b1c1e4e9615c9b3455dc111a5b1262505eb5ba6"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fcloudcms-javascript-driver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fcloudcms-javascript-driver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fcloudcms-javascript-driver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gitana%2Fcloudcms-javascript-driver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gitana","download_url":"https://codeload.github.com/gitana/cloudcms-javascript-driver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247980831,"owners_count":21027803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T15:21:06.048Z","updated_at":"2025-04-09T04:33:06.661Z","avatar_url":"https://github.com/gitana.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cloudcms-javascript-driver\n\nCloud CMS JavaScript Driver with support for ECMAScript Async, Promises and Callbacks.\n\nFor formal support and assistance, please visit \u003ca href=\"https://gitana.io\" title=\"Gitana Software\"\u003ehttps://gitana.io\u003c/a\u003e.\n\n## Installation\n\n```\nnpm install --save cloudcms\n```\n\n## Usage\n\nThis methods in this driver support the following patterns of usage:\n\n1. Async / Await\n2. Promises\n3. Callbacks\n\nYou're free to mix and match between these approaches as you see fit.\n\nHere are examples of each:\n\n### Async / Await\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\nconst apiKeys = {\n    \"clientKey\": \"\",\n    \"clientSecret\": \"\",\n    \"username\": \"\",\n    \"password\": \"\"    \n};\n\nvar repositoryId = \"f49e621853c33f501377\";\nvar branchId = \"master\";\nvar nodeId = \"821c40ab613d9b5bcbbc656b62229332\";\n\n(async function() {\n\n    var session = await cloudcms.connect(apiKeys);\n        \n    // read node\n    var node = await session.readNode(repositoryId, branchId, nodeId);\n    \n    // log result\n    console.log(\"Found node:\" + node.title);\n})();\n```\n\n### Promises\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\nconst apiKeys = {\n    \"clientKey\": \"\",\n    \"clientSecret\": \"\",\n    \"username\": \"\",\n    \"password\": \"\"    \n};\n\nvar repositoryId = \"f49e621853c33f501377\";\nvar branchId = \"master\";\n\ncloudcms.connect(apiKeys).then(function(session) {\n\n    // read node   \n    session.readNode(repositoryId, branchId, nodeId).then(function(node) {\n    \n        // log result\n        console.log(\"Found node:\" + node.title);    \n    });\n\n});\n```\n\n### Callbacks\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\nconst apiKeys = {\n    \"clientKey\": \"\",\n    \"clientSecret\": \"\",\n    \"username\": \"\",\n    \"password\": \"\"    \n};\n\nvar repositoryId = \"f49e621853c33f501377\";\nvar branchId = \"master\";\n\ncloudcms.connect(apiKeys, function(err, session) {\n\n    // read node   \n    session.readNode(repositoryId, branchId, nodeId, function(err, node) {\n    \n        // log result\n        console.log(\"Found node:\" + node.title);    \n    });\n\n});\n```\n\n## API Keys\n\nYou can either pass in your API Keys object to the `connect()` method or you can have the driver pick up the\nAPI keys from the following files in the local directory:\n\n- `gitana.json`\n- `cloudcms.json`\n\nFor example, the following code will simply read from disk:\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\nvar repositoryId = \"f49e621853c33f501377\";\nvar branchId = \"master\";\nvar nodeId = \"821c40ab613d9b5bcbbc656b62229332\";\n\n(async function() {\n\n    var session = await cloudcms.connect();\n        \n    // read node\n    var node = await session.readNode(repositoryId, branchId, nodeId);\n    \n    // log result\n    console.log(\"Found node:\" + node.title);\n})();\n```\n\n## Custom Session\n\nYou can supply your own session implementations to add your own methods.\n\nDefine your session class:\n\n```javascript\nvar DefaultSession = require(\"cloudcms/session/default/session\");\n\nclass CustomSession extends DefaultSession\n{\n    /**\n     * Creates an article.\n     *\n     * @param repository\n     * @param branch\n     * @param obj\n     */\n    createArticle(repository, branch, obj)\n    {\n        var callback = this.extractOptionalCallback(arguments);\n    \n        if (!obj) {\n            obj = {};\n        }\n        \n        obj._type = \"my:article\";\n        \n        // call through to the createNode method on the default session\n        return this.createNode(repository, branch, obj, callback);\n    }\n}\n\nmodule.exports = CustomSession;\n```\n\nThis extends the `session` object with a new method called `createArticle`.\n\nAnd then do the following to use it:\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\n(async function() {\n\n    var customSession = require(\"custom-session\");\n    cloudcms.session(customSession);\n\n    var session = await cloudcms.connect();\n    \n    var article = await session.createArticle(repository, branch, { \"title\": \"Hello World\" });\n\n})();\n```\n\nIf you want to add a new asynchronous method that adhere to the session's async support for callbacks, Promises and/or\nawait/async, you can use the `Helper.sessionFunction` method like this:\n\n```javascript\nvar DefaultSession = require(\"cloudcms/session/default/session\");\nvar Helper = require(\"cloudcms/helper\");\n\nclass CustomSession extends DefaultSession\n{\n    test()\n    {\n        // use the Helper.sessionFunction method to support Promise, callback or async/await\n        // put your work into the finish method\n        return Helper.sessionFunction.call(this, arguments, function(finish) {\n            return setTimeout(function() {\n                finish(null, 101);\n            }, 250);\n        });\n    }\n}\n\nmodule.exports = CustomSession;\n```\n\n## Session\n\nWhen a session connects, it maintains an Access Token and a Refresh Token.  The Access Token is passed as a bearer\ntoken via the `Authorization` header.  If the Access Token expires, the Refresh Token is used to acquire a new\nAccess Token.\n\n### Automatic Reauthentication\n\nIf the Refresh Token expires, you will need to re-authenticate.\n\nYou can set this up to happen automatically by using the `reauthenticate` method, like this:\n\n```javascript\nsession = await cloudcms.connect();\n\nsession.reauthenticate(function(done) {\n\n    // re-connect and use the done() function to pass back the new session\n    cloudcms.connect(function(err, newSession) {\n        done(err, newSession);\n    });\n});\n```\n\n### Manually refresh the Access Token\n\nYou can manually refresh the access token (using your Refresh Token) like this:\n\n```javascript\nawait session.refresh();\n```\n\n### Expire the Access / Refresh Token\n\nYou can also manually expire the issued Access and Refresh Token, like this:\n\n```javascript\nawait session.disconnect();\n```\n\n### Band\n\nIf you have multiple bands configured, you can configure your Session to perform all of its API calls\nagainst a designated band, like this:\n\n```javascript\nsession = await cloudcms.connect();\nsession.useBand(\"production\");\n```\n\nTo revert back to the default band:\n\n```javascript\nsession.useBand(null);\n```\n\n### TypeScript\n\nThe `cloudcms-javascript-driver` includes a TypeScript type interface to improve your editing experience and allow better integration in your TypeScript apps.\nHere's a quick example usage:\n\n```typescript\nimport { GitanaConfig, DefaultSession, PlatformObject, Rows } from 'cloudcms';\nimport * as CloudCMS from 'cloudcms';\n\nasync function myRequest(): Promise\u003cvoid\u003e {\n    var config: GitanaConfig = {\n        // ...\n    };\n\n    var session: DefaultSession = await CloudCMS.connect(config);\n\n    var repositoryId = \"myRepo\";\n    var branchId = \"master\";\n\n    var nodes: Rows\u003cNode\u003e = await session.queryNodes(repositoryId, branchId, { \"author\": \"Kurt Vonnegut\" });\n    nodes.rows.forEach((obj) =\u003e {\n        console.log(obj._doc);\n    })\n}\n\nmyRequest();\n```\n\nYou can also provide custom generic types to methods involving nodes to further describe returned node types in your TypeScript application:\n\n```typescript\nimport { Node, Rows } from 'cloudcms';\n\ninterface CustomType extends Node {\n    title: String,\n    aProp: String,\n    bProp: String\n}\n\nconst results: Rows\u003cCustomType\u003e = await session.queryNodes(repositoryId, branchId, { \"_type\": \"custom:type\" });\n```\n\n## Tests\n\nThis library uses Mocha and Chai for testing.\n\nTo test, first add `gitana.json` to the project root.\n\nTo run all tests:\n\n```\nnpm run alltests\n```\n\nTo run a single test (`node`):\n\n```\nnpm run test node\n```\n\n## Proxy\n\nConfigure the driver to use an HTTP or HTTPS proxy using the following environment variables to specify\nthe location of your proxy endpoint:\n\n- `HTTP_PROXY`\n- `HTTPS_PROXY`\n\nIf these environment variables are present when connecting to your Session, they will be incorporated \ninto the underlying engine's configuration to enable routing through your proxy.\n\nExample:\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\nprocess.env.HTTPS_PROXY = \"http://localhost:9090\";\n    \n(async function() {\n    var session = await cloudcms.connect();\n    console.log(\"Connected!\");\n})();\n```\n\nIn addition, the following environment variables are supported to prevent certain domains from routing\nthrough the HTTP/HTTPS PROXY endpoints.\n\n- `NO_PROXY`\n- `*_PROXY`\n\nFor more information, see:\nhttps://github.com/Rob--W/proxy-from-env?tab=readme-ov-file#environment-variables\n\nExample:\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\nprocess.env.HTTPS_PROXY = \"http://localhost:9090\";\n\n// route everything through \"localhost:9090\" except connections to https://api.cloudcms.com\nprocess.env.NO_PROXY = \"api.cloudcms.com\";\n    \n(async function() {\n    var session = await cloudcms.connect();\n    console.log(\"Connected!\");\n})();\n```\n\n## Custom Engine\n\nUse the `engine()` method to select the underlying HTTP client engine to use for connectivity to the API.\nThe following engines are supported:\n\n- `axios`\n- `fetch`\n\nYou can either pass in text (`axios` or `fetch`) to identify the engine you wish to use.  Or you can pass in\na reference to the class for the engine you wish to use.\n\nExample #1:\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\n(async function() {\n\n    cloudcms.engine(\"fetch\");\n\n    var session = await cloudcms.connect();\n    console.log(\"Connected!\");\n})();\n```\n\nExample #2:\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\n\n(async function() {\n\n    cloudcms.engine(cloudcms.FetchEngine);\n\n    var session = await cloudcms.connect();\n    console.log(\"Connected!\");\n})();\n```\n\nYou can also customize the configuration options for a given engine.  For example, you could configure\nthe Axios engine's options as shown below to provide your own custom HTTPS agent:\n\n```javascript\nconst cloudcms = require(\"cloudcms\");\nconst { HttpsProxyAgent} = require(\"https-proxy-agent\");\n\n(async function() {\n\n    cloudcms.engine(\"axios\", {\n        proxy: false,\n        httpsAgent: new HttpsProxyAgent(\"http://localhost:9090\")\n    });\n\n    var session = await cloudcms.connect(apiKeys);\n    console.log(\"Connected!\");\n})();\n```\n\n## Custom Storage\n\nTODO: how to configure Memory vs Redis\n\n## Custom Cache\n\nTODO: how to configure custom caching for JSON responses\n\n## Documentation\n\nPlease visit:\n\nhttps://gitana.io/documentation/gitana/4.0/developers/cookbooks/javascript2.html\nhttps://gitana.io/documentation/gitana/4.0/developers/drivers/javascript.html\n\n## Support\n\nFor support, please visit https://gitana.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitana%2Fcloudcms-javascript-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitana%2Fcloudcms-javascript-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitana%2Fcloudcms-javascript-driver/lists"}