diff --git a/CLAUDE.md b/CLAUDE.md index 31678b1..8ff7b8e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -83,7 +83,7 @@ Supported APIs: `us_street`, `us_zipcode`, `us_autocomplete`, `us_autocomplete_p Three credential types, each implementing a `sign(request)` method used by `SigningSender`: - **StaticCredentials** - Server-side: adds `auth-id` + `auth-token` query params -- **SharedCredentials** - Client-side/browser: adds embedded `key` param + `Referer` header. Cannot be used with POST (batch) requests. +- **SharedCredentials** - Client-side/browser: adds embedded `key` param + `Referer` header. Cannot be used with POST (batch) requests or the US Extract API (POST-only). - **BasicAuthCredentials** - Adds HTTP Basic Auth `Authorization` header ### Entry Point diff --git a/README.md b/README.md index 34bd0d5..10ebf97 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ console.log(response.result); // Array of address suggestions Three credential types are available: - **`StaticCredentials(authId, authToken)`** — Server-side authentication using auth-id and auth-token. -- **`SharedCredentials(key)`** — Client-side (browser) authentication using an embedded key. Does not support batch (POST) requests. +- **`SharedCredentials(key)`** — Client-side (browser) authentication using an embedded key. Embedded keys are restricted to HTTP GET, so they cannot be used for batch (POST) requests or with the US Extract API, which is POST-only. - **`BasicAuthCredentials(authId, authToken)`** — HTTP Basic Auth. ## Browser Usage @@ -84,7 +84,7 @@ const credentials = new SmartySDK.core.SharedCredentials("YOUR_EMBEDDED_KEY"); const client = new SmartySDK.core.ClientBuilder(credentials).buildUsStreetApiClient(); ``` -Note that `SharedCredentials` does not support batch (POST) requests — send one lookup at a time. +Note that `SharedCredentials` does not support batch (POST) requests — send one lookup at a time. The US Extract API is POST-only and so is unavailable with an embedded key. ### Features not available in the browser @@ -129,7 +129,7 @@ esbuild app.js --bundle --external:undici ### Batch Requests -Send up to 100 lookups in a single request (not available with `SharedCredentials`): +Send up to 100 lookups in a single request (requires `StaticCredentials` or `BasicAuthCredentials`; not available with `SharedCredentials`): ```javascript const batch = new SmartySDK.core.Batch(); diff --git a/examples/us_extract.mjs b/examples/us_extract.mjs index bcb3e56..ca3d00f 100644 --- a/examples/us_extract.mjs +++ b/examples/us_extract.mjs @@ -3,11 +3,8 @@ import SmartySDK from "smartystreets-javascript-sdk"; const SmartyCore = SmartySDK.core; const Lookup = SmartySDK.usExtract.Lookup; -// for client-side requests (browser/mobile), use this code: -// let key = process.env.SMARTY_EMBEDDED_KEY; -// const credentials = new SmartyCore.SharedCredentials(key); - -// for Server-to-server requests, use this code: +// The US Extract API is POST-only and embedded keys are restricted to GET, so this +// API requires secret keys: https://www.smarty.com/docs/cloud/authentication let authId = process.env.SMARTY_AUTH_ID; let authToken = process.env.SMARTY_AUTH_TOKEN; const credentials = new SmartyCore.BasicAuthCredentials(authId, authToken); diff --git a/examples/us_extract.ts b/examples/us_extract.ts index 25aaf3b..65e66b1 100644 --- a/examples/us_extract.ts +++ b/examples/us_extract.ts @@ -1,11 +1,7 @@ import { ClientBuilder, BasicAuthCredentials, LookupUSExtract } from "smartystreets-javascript-sdk"; -// for client-side requests (browser/mobile), use this code: -// import { SharedCredentials } from "smartystreets-javascript-sdk"; -// const key: string = process.env.SMARTY_EMBEDDED_KEY!; -// const credentials = new SharedCredentials(key); - -// for Server-to-server requests, use this code: +// The US Extract API is POST-only and embedded keys are restricted to GET, so this +// API requires secret keys: https://www.smarty.com/docs/cloud/authentication const authId = process.env.SMARTY_AUTH_ID!; const authToken = process.env.SMARTY_AUTH_TOKEN!; const credentials = new BasicAuthCredentials(authId, authToken); diff --git a/examples/us_street.mjs b/examples/us_street.mjs index 80ef993..cf7948b 100644 --- a/examples/us_street.mjs +++ b/examples/us_street.mjs @@ -3,11 +3,8 @@ import SmartySDK from "smartystreets-javascript-sdk"; const SmartyCore = SmartySDK.core; const Lookup = SmartySDK.usStreet.Lookup; -// for client-side requests (browser/mobile), use this code: -// let key = process.env.SMARTY_EMBEDDED_KEY; -// const credentials = new SmartyCore.SharedCredentials(key); - -// for Server-to-server requests, use this code: +// Batch requests are sent via HTTP POST. Embedded keys are restricted to GET, so +// batches require secret keys: https://www.smarty.com/docs/cloud/authentication let authId = process.env.SMARTY_AUTH_ID; let authToken = process.env.SMARTY_AUTH_TOKEN; const credentials = new SmartyCore.BasicAuthCredentials(authId, authToken); @@ -49,7 +46,7 @@ lookup3.street = "1600 Amphitheatre Parkway Mountain View, CA 94043"; // uncomment the following line to add a custom parameter // lookup3.addCustomParameter("max_candidates", 1); -// NOTE: batches are not supported when using SharedCredentials. +// NOTE: batch requests require secret keys; embedded keys cannot be used here. let batch = new SmartyCore.Batch(); batch.add(lookup1); batch.add(lookup2); diff --git a/examples/us_street.ts b/examples/us_street.ts index cc11022..aaacebc 100644 --- a/examples/us_street.ts +++ b/examples/us_street.ts @@ -5,12 +5,8 @@ import { Batch, } from "smartystreets-javascript-sdk"; -// for client-side requests (browser/mobile), use this code: -// import { SharedCredentials } from "smartystreets-javascript-sdk"; -// const key: string = process.env.SMARTY_EMBEDDED_KEY!; -// const credentials = new SharedCredentials(key); - -// for Server-to-server requests, use this code: +// Batch requests are sent via HTTP POST. Embedded keys are restricted to GET, so +// batches require secret keys: https://www.smarty.com/docs/cloud/authentication const authId = process.env.SMARTY_AUTH_ID!; const authToken = process.env.SMARTY_AUTH_TOKEN!; const credentials = new BasicAuthCredentials(authId, authToken); @@ -66,7 +62,7 @@ async function main(): Promise { // uncomment the following line to add a custom parameter // lookup3.addCustomParameter("max_candidates", 1); - // NOTE: batches are not supported when using SharedCredentials. + // NOTE: batch requests require secret keys; embedded keys cannot be used here. const batch = new Batch(); batch.add(lookup1); batch.add(lookup2); diff --git a/examples/us_zipcode.mjs b/examples/us_zipcode.mjs index 46ce7b2..5eb4913 100644 --- a/examples/us_zipcode.mjs +++ b/examples/us_zipcode.mjs @@ -3,11 +3,8 @@ import SmartySDK from "smartystreets-javascript-sdk"; const SmartyCore = SmartySDK.core; const Lookup = SmartySDK.usZipcode.Lookup; -// for client-side requests (browser/mobile), use this code: -// let key = process.env.SMARTY_EMBEDDED_KEY; -// const credentials = new SmartyCore.SharedCredentials(key); - -// for Server-to-server requests, use this code: +// Batch requests are sent via HTTP POST. Embedded keys are restricted to GET, so +// batches require secret keys: https://www.smarty.com/docs/cloud/authentication let authId = process.env.SMARTY_AUTH_ID; let authToken = process.env.SMARTY_AUTH_TOKEN; const credentials = new SmartyCore.BasicAuthCredentials(authId, authToken); @@ -37,6 +34,7 @@ lookup3.state = "AZ"; // uncomment the following line to add a custom parameter // lookup3.addCustomParameter("input_id", 1234); +// NOTE: batch requests require secret keys; embedded keys cannot be used here. let batch = new SmartyCore.Batch(); batch.add(lookup1); batch.add(lookup2); diff --git a/examples/us_zipcode.ts b/examples/us_zipcode.ts index 1f555d7..75e9087 100644 --- a/examples/us_zipcode.ts +++ b/examples/us_zipcode.ts @@ -5,12 +5,8 @@ import { Batch, } from "smartystreets-javascript-sdk"; -// for client-side requests (browser/mobile), use this code: -// import { SharedCredentials } from "smartystreets-javascript-sdk"; -// const key: string = process.env.SMARTY_EMBEDDED_KEY!; -// const credentials = new SharedCredentials(key); - -// for Server-to-server requests, use this code: +// Batch requests are sent via HTTP POST. Embedded keys are restricted to GET, so +// batches require secret keys: https://www.smarty.com/docs/cloud/authentication const authId = process.env.SMARTY_AUTH_ID!; const authToken = process.env.SMARTY_AUTH_TOKEN!; const credentials = new BasicAuthCredentials(authId, authToken); @@ -60,6 +56,7 @@ async function main(): Promise { // uncomment the following line to add a custom parameter // lookup3.addCustomParameter("input_id", 1234); + // NOTE: batch requests require secret keys; embedded keys cannot be used here. const batch = new Batch(); batch.add(lookup1); batch.add(lookup2);