API Utils

import * as apiUtils from '@green-stack/utils/apiUtils'

Collection of utility functions for handling API requests, parameters, and security:

- - - apiUtils.ts

Disclaimer - Server Only

These utilities are designed for server-side use only. They are not intended for client-side execution and may not work correctly in a browser environment.

JSON Utils

`validateJSON()`

Checks whether a string is valid JSON.

validateJSON('{"name": "John"}') // => true
validateJSON('{"name": John}') // => false (missing quotes)
validateJSON('not json') // => false

`parseIfJSON()`

Attempts to parse a string if it’s valid JSON, otherwise returns the original value.

parseIfJSON('{"name": "John"}') // => { name: 'John' }
parseIfJSON('not json') // => 'not json'
parseIfJSON({ already: 'object' }) // => { already: 'object' }

API Parameter Utils

`getApiParam()`

Gets a specific property by key from supplied API sources (query, params, body, args, context).

const apiSources = {
    query: { id: '123' },
    body: { name: 'John' },
    params: { type: 'user' }
}
 
getApiParam('id', apiSources) // => '123'
getApiParam('name', apiSources) // => 'John'
getApiParam('type', apiSources) // => 'user'
getApiParam('nonexistent', apiSources) // => undefined

`getApiParams()`

Get multiple API parameters from supplied API sources.

const apiSources = {
    query: { id: '123' },
    body: { name: 'John' },
    params: { type: 'user' }
}
 
getApiParams(['id', 'name'], apiSources)
// => { id: '123', name: 'John' }
 
getApiParams('id name type', apiSources)
// => { id: '123', name: 'John', type: 'user' }

`getUrlParams()`

Extracts and parses query parameters from a URL.

getUrlParams('https://api.example.com/users?id=123&name=John')
// => { id: 123, name: 'John' }
 
getUrlParams('https://api.example.com/users')
// => {}

Security Utils

`createHmac()`

Creates a cryptographic signature based on the data and chosen algorithm.

createHmac('sensitive-data', 'sha256')
// => 'hashed-signature'
 
createHmac('sensitive-data', 'md5')
// => 'hashed-signature'

`encrypt()`

Encrypts data using AES encryption with a secret key.

const encrypted = encrypt('sensitive-data', 'my-secret-key')
// => 'encrypted-string'
 
// Using APP_SECRET environment variable
const encrypted = encrypt('sensitive-data')
// => 'encrypted-string'

`decrypt()`

Decrypts data that was encrypted using the encrypt() function.

const decrypted = decrypt(encrypted, 'my-secret-key')
// => 'sensitive-data'
 
// Using APP_SECRET environment variable
const decrypted = decrypt(encrypted)
// => 'sensitive-data'

Header Context Utils

`createMiddlewareContext()`

Adds serializable context data to request headers (signed based on APP_SECRET).

const headers = await createMiddlewareContext(
    request,
    { userId: '123', role: 'admin' },
    { 'X-Custom-Header': 'value' }
)
// => Headers object with context and custom headers

`getHeaderContext()`

Extracts and validates header context from various request types.

// From NextApiRequest
const context = getHeaderContext(nextApiRequest)
// => { userId: '123', role: 'admin' }
 
// From standard Request
const context = getHeaderContext(request)
// => { userId: '123', role: 'admin' }
 
// From GetServerSidePropsContext
const context = getHeaderContext(context.req)
// => { userId: '123', role: 'admin' }

Note: Both header context utilities require the APP_SECRET environment variable to be set for signing and validation.

Fire and Forget Utils

`fireGetAndForget()`

Fires a GET request and ignores whether it succeeds or not (useful for webhooks).

fireGetAndForget('https://api.example.com/webhook')
// => true (immediately, doesn't wait for response)
 
// With custom config
fireGetAndForget('https://api.example.com/webhook', {
    headers: { 'X-API-Key': 'secret' }
})

`firePostAndForget()`

Fires a POST request and ignores whether it succeeds or not (useful for webhooks).

firePostAndForget('https://api.example.com/webhook', { event: 'user.created' })
// => true (immediately, doesn't wait for response)
 
// With custom config
firePostAndForget('https://api.example.com/webhook', 
    { event: 'user.created' },
    { headers: { 'X-API-Key': 'secret' } }
)

arrayUtils