v0.2.0

.eslintignore

@@ -0,0 +1,2 @@
+build
+coverage

.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['*']
+
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    name: Build [Node.js ${{ matrix.node-version }}]
+    runs-on: ubuntu-22.04
+
+    strategy:
+      matrix:
+        include:
+          - node-version: 18.x
+            publish: false
+          - node-version: 20.x
+            publish: true # Publish on npm
+          - node-version: 22.x
+            publish: false
+
+    env:
+      CI: true
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      ##########################################################################
+      # Build
+      ##########################################################################
+
+      - name: Set up Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install
+        run: yarn install
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Build
+        run: yarn build
+
+      - name: Test
+        run: yarn test
+
+      ##########################################################################
+      # Publish
+      ##########################################################################
+
+      - name: Check tag format
+        id: check-tag-format
+        if: startsWith(github.ref, 'refs/tags/') && matrix.publish
+        uses: nowsprinting/check-version-format-action@v4
+
+      - name: Exit on invalid tag format
+        if: startsWith(github.ref, 'refs/tags/') && !steps.check-tag-format.outputs.is_valid && matrix.publish
+        run: echo "Tag must follow SemVer convention. Aborting." && exit 1
+
+      - name: Get release type
+        if: startsWith(github.ref, 'refs/tags/') && matrix.publish
+        id: get-release-type
+        uses: actions/github-script@v7
+        with:
+          result-encoding: string
+          script: |
+            const regex = /(alpha|beta)/
+            const refName = context.ref.replace('refs/tags/', '')
+            console.log(`Ref tag: ${refName}`)
+            const releaseTypeMatch = refName.match(regex)
+            if (!releaseTypeMatch) {
+              releaseType = 'latest'
+            } else {
+              releaseType =  releaseTypeMatch[0]
+            }
+            console.log(`Release type: ${releaseType}`)
+            return releaseType
+
+      # TODO: Enable after reaching 1.0.0.
+      # This may indicate that the tag set has a typo, e.g., alpah, betta, etc.
+      # - name: Verify tag format
+      #   if: steps.check-tag-format.outputs.is_stable == 'false' && steps.get-release-type.outputs.result == 'latest'
+      #   run: echo "Tag set may be incorrect. Please, review" && exit 1
+
+      - name: Configure yarn to publish packages
+        if: startsWith(github.ref, 'refs/tags/') && matrix.publish
+        env:
+          # The following token has been manually issued in the CartoDB
+          # organization for npmjs.com
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_CARTODB_AUTH_TOKEN }}
+        run: |
+          yarn config set npmPublishRegistry "https://registry.npmjs.org/"
+          yarn config set npmAuthToken "${NODE_AUTH_TOKEN}"
+
+      - name: Publish package
+        if: startsWith(github.ref, 'refs/tags/') && matrix.publish
+        env:
+          RELEASE_TYPE: ${{ steps.get-release-type.outputs.result }}
+        run: yarn npm publish --tag ${RELEASE_TYPE}

.gitignore

@@ -0,0 +1,13 @@
+node_modules
+build
+coverage
+custom-elements.json
+
+# https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions

.prettierrc.json

@@ -0,0 +1,7 @@
+{
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "singleQuote": true,
+  "bracketSpacing": false,
+  "arrowParens": "always"
+}

.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+## 0.2
+
+### 0.2.0
+
+- Initial release

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+_Contributions are subject to CARTO's [community contributions policy](https://carto.com/contributions/)._
+
+## Local development requirements
+
+- Yarn v4+
+- Node.js v18+
+
+## Quickstart
+
+To install and build `@carto/api-client` locally from source:
+
+```bash
+# install dependencies
+yarn
+
+# build package once
+yarn build
+
+# build package and watch for changes
+yarn build --watch
+
+# build package, watch for changes, and start a local server for examples
+yarn dev
+```
+
+After running `yarn dev`, a browser window will open with links each example. The local URL will generally be `localhost:5173`.
+
+To run tests, coverage, or a linter:
+
+```bash
+# run tests once
+yarn test
+
+# run tests and watch for changes
+yarn test:watch
+
+# run tests and gather code coverage
+yarn coverage
+
+# lint for style and formatting errors
+yarn lint
+
+# fix style and formatting errors
+yarn format
+```
+
+Tests, coverage, and other development-related scripts are defined in `package.json#scripts`.
+
+## Releases
+
+1. Update changelog
+
+2. Create a new version: `yarn version [ major | minor | patch | prerelease ]`
+
+3. Commit, tag, and push to GitHub: `yarn postversion`
+
+4. GitHub CI will publish to npm automatically

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CARTO
+
+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.

README.md

@@ -0,0 +1,139 @@
+# `@carto/api-client`
+
+JavaScript (and TypeScript) client library for [CARTO](https://carto.com/) APIs and framework-agnostic [CARTO + deck.gl](https://docs.carto.com/carto-for-developers/carto-for-deck.gl) applications.
+
+Includes:
+
+- [Widget](https://docs.carto.com/carto-for-developers/carto-for-react/guides/widgets) APIs
+- … TBD
+
+## Installation
+
+Install `@carto/api-client`:
+
+```bash
+npm install --save @carto/api-client
+```
+
+## Documentation
+
+### Fetching data
+
+Import `vectorTableSource`, `vectorQuerySource`, and other data source functions
+from the `@carto/api-client` package. These are drop-in replacements for the equivalent functions from the `@deck.gl/carto` package, and the same data source may be used with any number of layers or widgets. Tileset sources are not yet supported.
+
+```javascript
+import { vectorTableSource } from '@carto/api-client';
+
+const data = await vectorTableSource({
+  accessToken: '••••',
+  connectionName: 'carto_dw',
+  tableName: 'carto-demo-data.demo_tables.retail_stores'
+});
+
+// → {name: string; value: number}[]
+const categories = await data.widgetSource.getCategories({
+  column: 'store_type',
+  operation: 'count',
+});
+
+// → {value: number}
+const formula = await data.widgetSource.getFormula({operation: 'count'});
+
+// → {totalCount: number; rows: Record<string, number | string>[]}
+const table = await data.widgetSource.getTable({
+  columns: ['a', 'b', 'c'],
+  sortBy: ['a'],
+  rowsPerPage: 20
+});
+
+...
+```
+
+### Column filter
+
+To filter the widget source by a non-geospatial column, pass a `filters`
+property to the source factory function.
+
+```javascript
+import {vectorTableSource} from '@carto/api-client';
+
+const data = await vectorTableSource({
+  accessToken: '••••',
+  connectionName: 'carto_dw',
+  tableName: 'carto-demo-data.demo_tables.retail_stores',
+  filters: {
+    store_type: {owner: 'widget-id', values: ['retail']},
+  },
+});
+```
+
+By default, filters affect all layers and widgets using a given data source. To
+exclude a particular widget from the filter, pass a `filterOwner` parameter
+matching the filters from which it should be excluded. In some cases, a widget's
+results should not be affected by a filter that the widget itself created.
+
+```javascript
+// → {name: string; value: number}[]
+const categories = await data.widgetSource.getCategories({
+  filterOwner: 'widget-id',
+  column: 'store_type',
+  operation: 'count',
+});
+```
+
+### Spatial filter
+
+To filter the widget source to a spatial region, pass a `spatialFilter` parameter (GeoJSON Polygon or MultiPolygon geometry) to any data fetching function.
+
+```javascript
+// → {name: string; value: number}[]
+const categories = await data.widgetSource.getCategories({
+  column: 'store_type',
+  operation: 'count',
+  spatialFilter: {
+    type: "Polygon"
+    coordinates: [
+      [
+        [-74.0562, 40.8331],
+        [-74.0562, 40.6933],
+        [-73.8734, 40.6933],
+        [-73.8734, 40.8331],
+        [-74.0562, 40.8331]
+      ]
+    ],
+  }
+});
+```
+
+To create a spatial filter from the current [deck.gl `viewState`](https://deck.gl/docs/developer-guide/views#using-a-view-with-view-state):
+
+```javascript
+import {WebMercatorViewport} from '@deck.gl/core';
+import {createViewportSpatialFilter} from '@carto/api-client';
+
+const viewport = new WebMercatorViewport(viewState);
+const spatialFilter = createViewportSpatialFilter(viewport.getBounds());
+```
+
+### Specifying columns to fetch
+
+Factory functions, like `vectorTableSource`, support both layers
+and widgets. While reusing the same sources has advantages, including simplicity, it's important to understand which columns are fetched, which
+depends on the source type.
+
+- **Table sources:** Layers fetch only columns specified by the `columns`
+  parameter. Widgets fetch only the columns they need, and are unaffected by
+  the `columns` parameter.
+- **Query sources:** Source SQL query must include all columns needed by any
+  layers or widgets using the source. Layers fetch only the subset specified
+  by the `columns` parameter. Widgets fetch only the subset they need, and are unaffected by the `columns` parameter.
+- **Tileset sources:** Not yet supported.
+
+## Versioning
+
+Package versioning follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+## License
+
+Provided as open source under [MIT License](./LICENSE.md).