@carto/api-client 0.0.1-0 → 0.0.1-2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# CHANGELOG
+
+## 0.0
+
+### 0.0.1 (UNRELEASED)
+
+- Initial release

package/README.md

@@ -1,24 +1,136 @@
 # `@carto/api-client`
 
-## References
+WORK IN PROGRESS.
 
-- [Product feature brief](https://docs.google.com/document/d/1ZWiVB_rgXf1WAEF1TjJgEHxp92kREYQrWG3O8jYV0Zk/edit)
-- [Architecture document](https://app.shortcut.com/cartoteam/write/IkRvYyI6I3V1aWQgIjY2MzE1NDU0LTIyZTAtNDI4YS04NzMzLTc3YzZjN2I2MjVjYSI=?commentId=e509d33c6cdedf90599a5d3a937336d8e&commentThreadId=e7dbf03c9bd7b0fd3de40ebacbea67ee9)
+## Installation
 
-## Quickstart
+Install `@carto/api-client`:
 
 ```bash
-# install dependencies
-yarn
+npm install --save @carto/api-client
+```
+
+## Documentation
+
+WORK IN PROGRESS.
+
+### 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 = vectorTableSource({
+  accessToken: '••••',
+  connectionName: 'carto_dw',
+  tableName: 'carto-demo-data.demo_tables.retail_stores'
+});
+
+const { widgetSource } = await data;
+
+// → {name: string; value: number}[]
+const categories = await widgetSource.getCategories({
+  column: 'store_type',
+  operation: 'count',
+});
+
+// → {value: number}
+const formula = await widgetSource.getFormula({operation: 'count'});
+
+// → {totalCount: number; rows: Record<string, number | string>[]}
+const table = await widgetSource.getTable({
+  columns: ['a', 'b', 'c'],
+  sortBy: ['a'],
+  rowsPerPage: 20
+});
+
+...
+```
+
+### Column filter
 
-# build package once
-yarn build
+To filter the widget source by a non-geospatial column, pass a `filters`
+property to the source factory function.
 
-# build package and watch for changes
-yarn build --watch
+```javascript
+import {vectorTableSource} from '@carto/api-client';
 
-# build package, watch for changes, and start a local server for examples
-yarn dev
+const data = vectorTableSource({
+  accessToken: '••••',
+  connectionName: 'carto_dw',
+  tableName: 'carto-demo-data.demo_tables.retail_stores',
+  filters: {
+    store_type: {owner: 'widget-id', values: ['retail']},
+  },
+});
 ```
 
-After running `yarn dev`, a browser window should open with links to examples. Unless a different port number is required, the local URL will be `localhost:5173`.
+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 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 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';
+
+function createViewStatePolygon(viewState) {
+  const viewport = new WebMercatorViewport(viewState);
+  return {
+    type: 'Polygon',
+    coordinates: [
+      [
+        viewport.unproject([0, 0]),
+        viewport.unproject([viewport.width, 0]),
+        viewport.unproject([viewport.width, viewport.height]),
+        viewport.unproject([0, viewport.height]),
+        viewport.unproject([0, 0]),
+      ],
+    ],
+  };
+}
+```
+
+## Versioning
+
+Package versioning follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+## License
+
+UNLICENSED. WORK IN PROGRESS.