Skip to main content

JavaScript SDK and Integration

The public JavaScript SDK repository contains a browser client, Cognito helper, and web-form handler. It is separate from the generated TypeScript SDK, which can also be used from JavaScript applications.

Published package versus repository source​

The published npm package inspected for this guide is 1.1.0. The repository's build package declares 2.0.0, but that is not the version published on npm. Do not assume installing from npm provides the repository's current login behavior or API coverage.

npm install formkiq-client-sdk-javascript@1.1.0

The package includes dist/web-cjs/formkiq-client-sdk-cjs.js and dist/es6/formkiq-client-sdk-es6.js. Inspect the actual bundle format before importing it: the published file under the es6 folder is a UMD bundle, not a native ES-module export. This browser client also accesses the DOM for form handling, so do not assume it is a Node server client.

Browser initialization​

Serve the reviewed browser bundle with your application's static assets. The CommonJS-for-web bundle defines FormkiqClient for the script-based usage below:

<script src="/vendor/formkiq-client-sdk-cjs.js"></script>
<script>
const client = new FormkiqClient(
'example.execute-api.us-east-2.amazonaws.com',
'us-east-2_EXAMPLE',
'example-app-client-id'
);
</script>

For this published package, use the stack's JWT API hostname without https://, plus the Cognito user pool and app client IDs. API instance properties use lower camel case, such as versionApi and documentsApi; an older README's VersionApi property is not the instance API.

Authentication helper behavior

In published version 1.1.0, login() starts Cognito callbacks but does not return a Promise that resolves with the authenticated session. Writing await client.login(...) does not reliably wait for sign-in. Do not issue an API call immediately afterward assuming authentication completed. Use an application-owned Cognito/SSO flow, and evaluate the generated TypeScript client or direct API integration for new work. Test MFA, new-password challenges, refresh, and sign-out explicitly.

Once a valid session has been established for the client, client.versionApi.getVersion() calls the backend version endpoint. SDK package and backend versions are independent; do not assume this older package covers every v1.19.2 endpoint.

Direct JavaScript API example​

For a small integration with an existing authenticated session, ordinary fetch makes the credential and error handling explicit. Obtain accessToken from your application's configured login flow; never put a real token or password in source.

async function listSites(httpApiUrl, accessToken) {
const response = await fetch(`${httpApiUrl.replace(/\/$/, '')}/sites`, {
headers: { Authorization: `Bearer ${accessToken}` },
});
const text = await response.text();
if (!response.ok) {
throw new Error(`FormKiQ request failed with HTTP ${response.status}`);
}
return text ? JSON.parse(text) : {};
}

const result = await listSites(httpApiUrl, accessToken);
console.log(result.sites);

Use HttpApiUrl including https:// for this direct-fetch example. IAM and API-key endpoints require their respective credentials/signing. Configure CORS and session lifetimes for browser use, and errors and pagination for list operations.

Web forms​

The browser SDK can bind forms marked class="fkq-form" and exposes webFormsHandler.submitFormkiqForm(form). This is client-side convenience, not authorization or server-side validation. Give public intake only the intended webhook capability; never embed an administrative password or long-lived integration key in browser code.

Check the actual webhook contract against the deployment. Do not assume a legacy form example supports every current public/private mode, endpoint, attachment, or processing requirement.

Choose and pin the client​

For new applications, compare required operations against the generated TypeScript SDK and the pinned OpenAPI reference. Use a server-side proxy or an appropriate AWS SDK for server-to-server SigV4 rather than treating the browser package as a universal authentication library. Pin dependencies and verify the package actually shipped, not just the repository's current version field.