@carto/api-client 0.0.35 → 0.0.37

package/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.

package/README.md

@@ -1,6 +1,11 @@
 # `@carto/api-client`
 
-WORK IN PROGRESS.
+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
 
@@ -127,10 +132,24 @@ function createViewStatePolygon(viewState) {
 }
 ```
 
+### 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
 
-UNLICENSED. WORK IN PROGRESS.
+Provided as open source under [MIT License](./LICENSE.md).

package/build/api-client.cjs

@@ -276,7 +276,8 @@ function executeModel(props) {
     apiVersion,
     apiBaseUrl,
     accessToken,
-    connectionName
+    connectionName,
+    clientId
   } = source;
   assert(apiBaseUrl, 'executeModel: missing apiBaseUrl');
   assert(accessToken, 'executeModel: missing accessToken');
@@ -291,7 +292,7 @@ function executeModel(props) {
   const queryParameters = source.queryParameters ? JSON.stringify(source.queryParameters) : '';
   const queryParams = {
     type,
-    client: getClient(),
+    client: clientId,
     source: data,
     params: JSON.stringify(params),
     queryParameters,
@@ -815,7 +816,7 @@ const V3_MINOR_VERSION = '3.4';
 const MAX_GET_LENGTH = 8192;
 const DEFAULT_PARAMETERS = {
   v: V3_MINOR_VERSION,
-  deckglVersion: "0.0.35"
+  deckglVersion: "0.0.37"
 };
 const DEFAULT_HEADERS = {
   Accept: 'application/json',
@@ -1068,7 +1069,7 @@ const h3TableSource$1 = async function (options) {
   return baseSource('table', options, urlParameters);
 };
 
-const h3TilesetSource$1 = async function (options) {
+const h3TilesetSource = async function (options) {
   const {
     tableName
   } = options;
@@ -1132,7 +1133,7 @@ const quadbinTableSource$1 = async function (options) {
   return baseSource('table', options, urlParameters);
 };
 
-const quadbinTilesetSource$1 = async function (options) {
+const quadbinTilesetSource = async function (options) {
   const {
     tableName
   } = options;
@@ -1194,7 +1195,7 @@ const vectorTableSource$1 = async function (options) {
   return baseSource('table', options, urlParameters);
 };
 
-const vectorTilesetSource$1 = async function (options) {
+const vectorTilesetSource = async function (options) {
   const {
     tableName
   } = options;
@@ -1209,29 +1210,22 @@ const vectorTilesetSource$1 = async function (options) {
   boundaryTableSource,
   h3QuerySource: h3QuerySource$1,
   h3TableSource: h3TableSource$1,
-  h3TilesetSource: h3TilesetSource$1,
+  h3TilesetSource,
   rasterSource,
   quadbinQuerySource: quadbinQuerySource$1,
   quadbinTableSource: quadbinTableSource$1,
-  quadbinTilesetSource: quadbinTilesetSource$1,
+  quadbinTilesetSource,
   vectorQuerySource: vectorQuerySource$1,
   vectorTableSource: vectorTableSource$1,
-  vectorTilesetSource: vectorTilesetSource$1
+  vectorTilesetSource
 });
 
 /** Wrapper adding Widget API support to [vectorTableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 
-/** Wrapper adding Widget API support to [quadbinTilesetSource](https://deck.gl/docs/api-reference/carto/data-sources). */
-const quadbinTilesetSource = function () {
-  try {
-    throw new Error('not implemented');
-  } catch (e) {
-    return Promise.reject(e);
-  }
-};
 /** Wrapper adding Widget API support to [quadbinQuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
 const quadbinQuerySource = function (props) {
   try {
+    assignDefaultProps(props);
     return Promise.resolve(quadbinQuerySource$1(props)).then(function (response) {
       return {
         ...response,
@@ -1245,6 +1239,7 @@ const quadbinQuerySource = function (props) {
 /** Wrapper adding Widget API support to [quadbinTableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 const quadbinTableSource = function (props) {
   try {
+    assignDefaultProps(props);
     return Promise.resolve(quadbinTableSource$1(props)).then(function (response) {
       return {
         ...response,
@@ -1255,17 +1250,10 @@ const quadbinTableSource = function (props) {
     return Promise.reject(e);
   }
 };
-/** Wrapper adding Widget API support to [h3TilesetSource](https://deck.gl/docs/api-reference/carto/data-sources). */
-const h3TilesetSource = function () {
-  try {
-    throw new Error('not implemented');
-  } catch (e) {
-    return Promise.reject(e);
-  }
-};
 /** Wrapper adding Widget API support to [h3QuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
 const h3QuerySource = function (props) {
   try {
+    assignDefaultProps(props);
     return Promise.resolve(h3QuerySource$1(props)).then(function (response) {
       return {
         ...response,
@@ -1279,6 +1267,7 @@ const h3QuerySource = function (props) {
 /** Wrapper adding Widget API support to [h3TableSource](https://deck.gl/docs/api-reference/carto/data-sources). */
 const h3TableSource = function (props) {
   try {
+    assignDefaultProps(props);
     return Promise.resolve(h3TableSource$1(props)).then(function (response) {
       return {
         ...response,
@@ -1289,17 +1278,10 @@ const h3TableSource = function (props) {
     return Promise.reject(e);
   }
 };
-/** Wrapper adding Widget API support to [vectorTilesetSource](https://deck.gl/docs/api-reference/carto/data-sources). */
-const vectorTilesetSource = function () {
-  try {
-    throw new Error('not implemented');
-  } catch (e) {
-    return Promise.reject(e);
-  }
-};
 /** Wrapper adding Widget API support to [vectorQuerySource](https://deck.gl/docs/api-reference/carto/data-sources). */
 const vectorQuerySource = function (props) {
   try {
+    assignDefaultProps(props);
     return Promise.resolve(vectorQuerySource$1(props)).then(function (response) {
       return {
         ...response,
@@ -1312,6 +1294,7 @@ const vectorQuerySource = function (props) {
 };
 const vectorTableSource = function (props) {
   try {
+    assignDefaultProps(props);
     return Promise.resolve(vectorTableSource$1(props)).then(function (response) {
       return {
         ...response,
@@ -1322,6 +1305,14 @@ const vectorTableSource = function (props) {
     return Promise.reject(e);
   }
 };
+function assignDefaultProps(props) {
+  if (typeof deck !== 'undefined' && deck && deck.VERSION) {
+    props.clientId ||= 'deck-gl-carto';
+    // TODO: Uncomment if/when `@deck.gl/carto` devDependency is removed,
+    // and source functions are moved here rather than wrapped.
+    // props.deckglVersion ||= deck.VERSION;
+  }
+}
 
 exports.WidgetBaseSource = WidgetBaseSource;
 exports.WidgetQuerySource = WidgetQuerySource;
@@ -1329,12 +1320,9 @@ exports.WidgetTableSource = WidgetTableSource;
 exports.getClient = getClient;
 exports.h3QuerySource = h3QuerySource;
 exports.h3TableSource = h3TableSource;
-exports.h3TilesetSource = h3TilesetSource;
 exports.quadbinQuerySource = quadbinQuerySource;
 exports.quadbinTableSource = quadbinTableSource;
-exports.quadbinTilesetSource = quadbinTilesetSource;
 exports.setClient = setClient;
 exports.vectorQuerySource = vectorQuerySource;
 exports.vectorTableSource = vectorTableSource;
-exports.vectorTilesetSource = vectorTilesetSource;
 //# sourceMappingURL=api-client.cjs.map