chore(release): Add version and publish macros

CHANGELOG.md

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

CONTRIBUTING.md

@@ -1,9 +1,66 @@
 # Contributing
 
+## Local development requirements
+
+- Yarn v4+
+- Node.js v18+
+
 ## Quickstart
 
-TODO
+```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 to examples. Local URL will be `localhost:5173`, or may use another available port number.
+
+Tests, coverage, and other developmen-related scripts are defined in `package.json#scripts`.
+
+```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
+```
+
+## Releases
 
-## Dependencies
+> **TODO:** Configure an automatic release process with GitHub actions.
 
-New `dependencies` are added to individual packages in `packages/*` as required. New `devDependencies` are added to the workspace root `package.json` only. The `devDependencies` for all `packages/*/package.json` should be empty.
+1. Create a new version
+  ```bash
+  yarn version [ major | minor | patch | prerelease ]
+  ```
+2. Update changelog and commit
+  ```bash
+  git add -u
+  git commit -m "vX.Y.Z"
+  git tag -a "vX.Y.Z"
+  ```
+3. Publish to npm
+  ```bash
+  yarn npm publish [ --tag alpha ]
+  ```
+4. Push to GitHub
+  ```bash
+  git push && git push --tags
+  ```

README.md

@@ -1,24 +1,112 @@
 # `@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
+
+```javascript
+import { vectorTableSource } from '@carto/api-client';
+
+const data = vectorTableSource({
+  accessToken: '••••',
+  connectionName: 'carto_dw',
+  tableName: 'carto-demo-data.demo_tables.retail_stores'
+});
 
-# build package once
-yarn build
+const { widgetSource } = await data;
 
-# build package and watch for changes
-yarn build --watch
+// → {name: string; value: number}[]
+const categories = await widgetSource.getCategories({
+  column: 'store_type',
+  operation: 'count',
+});
 
-# build package, watch for changes, and start a local server for examples
-yarn dev
+// → {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
+});
+
+...
 ```
 
-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`.
+### 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 = 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 widgetSource.getCategories({
+  filterOwner: 'widget-id',
+  column: 'store_type',
+  operation: 'count',
+});
+```
+
+### Spatial filter
+
+To filter the widget source by a geospatial column, including the map viewport,
+pass a `spatialFilter` parameter (GeoJSON Polygon or MultiPolygon geometry) to any widget 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]
+      ]
+    ],
+  }
+});
+```
+
+## Versioning
+
+Package versioning follows [Semantic Versioning 2.0.0](https://semver.org/).
+
+## License
+
+UNLICENSED. WORK IN PROGRESS.

package.json

@@ -1,7 +1,11 @@
 {
   "name": "@carto/api-client",
-  "private": true,
-  "packageManager": "[email protected]",
+  "version": "0.0.1-1",
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha"
+  },
+  "packageManager": "[email protected]",
   "author": "Don McCurdy <[email protected]>",
   "license": "UNLICENSED",
   "type": "module",
@@ -31,7 +35,9 @@
     "coverage": "vitest run --coverage",
     "lint": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --check",
     "format": "prettier \"**/*.{cjs,html,js,json,md,ts}\" --ignore-path ./.eslintignore --write",
-    "clean": "rimraf build/*"
+    "clean": "rimraf build/*",
+    "prepack": "yarn clean && yarn build",
+    "prepublish": "yarn lint && yarn test"
   },
   "files": [
     "build",