diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ccc29a9..b8ae2efb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Implement Common Media Server Data (CMSD) utilities [#35](https://github.com/streaming-video-technology-alliance/common-media-library/issues/35) +- Add request and response interceptors API ## [0.4.5] - 2023-10-12 diff --git a/lib/config/common-media-library.api.md b/lib/config/common-media-library.api.md index d49469ee..2a2b985f 100644 --- a/lib/config/common-media-library.api.md +++ b/lib/config/common-media-library.api.md @@ -174,6 +174,32 @@ export { CmStreamType as CmsdStreamType } // @beta export type CmValue = CmObjectType | CmStreamingFormat | CmStreamType | string | number | boolean | symbol | SfToken; +// @beta +export interface CommonMediaRequest { + cmcd?: Cmcd; + credentials?: RequestCredentials; + customData?: any; + headers?: Record; + method: string; + mode?: RequestMode; + responseType?: string; + timeout?: number; + url: string; +} + +// @beta +export interface CommonMediaResponse { + data?: any; + headers?: Record; + redirected?: boolean; + request: CommonMediaRequest; + resourceTiming: ResourceTiming; + status?: number; + statusText?: string; + type?: string; + url?: string; +} + // @beta export function decodeCmcd(cmcd: string): Cmcd; @@ -248,6 +274,26 @@ export type Id3Frame = DecodedId3Frame; // @internal export function isId3TimestampFrame(frame: Id3Frame): boolean; +// @beta +export type RequestInterceptor = (request: CommonMediaRequest) => Promise; + +// @beta +export interface ResourceTiming { + // (undocumented) + duration?: number; + // (undocumented) + encodedBodySize: number; + // (undocumented) + responseEnd?: number; + // (undocumented) + responseStart?: number; + // (undocumented) + startTime: number; +} + +// @beta +export type ResponseInterceptor = (response: CommonMediaResponse) => Promise; + // @beta export function roundToEven(value: number, precision: number): number; diff --git a/lib/package.json b/lib/package.json index cba388d8..b90b5871 100644 --- a/lib/package.json +++ b/lib/package.json @@ -58,7 +58,9 @@ "CMSD", "RFC8941", "Structured Field Values", - "ID3" + "ID3", + "Common Media Request", + "Common Media Response" ], "scripts": { "build": "node --no-warnings --loader ts-node/esm ../scripts/build.ts", diff --git a/lib/src/index.ts b/lib/src/index.ts index b9148cfd..fecd846e 100644 --- a/lib/src/index.ts +++ b/lib/src/index.ts @@ -7,5 +7,6 @@ export * from './cmcd.js'; export * from './cmsd.js'; export type * from './cta.js'; export * from './id3.js'; +export type * from './request.js'; export * from './structuredfield.js'; export * from './utils.js'; diff --git a/lib/src/request.ts b/lib/src/request.ts new file mode 100644 index 00000000..f340586b --- /dev/null +++ b/lib/src/request.ts @@ -0,0 +1,10 @@ +/** + * Common Media Request + * + * @packageDocumentation + */ +export type { CommonMediaRequest } from './request/CommonMediaRequest.js'; +export type { CommonMediaResponse } from './request/CommonMediaResponse.js'; +export type { RequestInterceptor } from './request/RequestInterceptor.js'; +export type { ResponseInterceptor } from './request/ResponseInterceptor.js'; +export type { ResourceTiming } from './request/ResourceTiming.js'; diff --git a/lib/src/request/CommonMediaRequest.ts b/lib/src/request/CommonMediaRequest.ts new file mode 100644 index 00000000..80d3e272 --- /dev/null +++ b/lib/src/request/CommonMediaRequest.ts @@ -0,0 +1,57 @@ +import { Cmcd } from '../cmcd.js'; + +/** + * Common request API. + * + * @group Request + * + * @beta + */ +export interface CommonMediaRequest { + + /** + * The URL of the request. + */ + url: string + + /** + * The request's method (GET, POST, etc). + */ + method: string + + /** + * The response type with which the response from the server shall be compatible. + */ + responseType?: string + + /** + * The headers object associated with the request. + */ + headers?: Record + + /** + * Indicates whether the user agent should send or receive cookies from the other domain in the case of cross-origin requests. + */ + credentials?: RequestCredentials + + /** + * The mode of the request (e.g., cors, no-cors, same-origin, etc). + */ + mode?: RequestMode + + /** + * The number of milliseconds the request can take before automatically being terminated. + * If undefined or value is 0 then there is no timeout. + */ + timeout?: number + + /** + * The Common Media Client Data (CMCD) that comprises media and request related information. + */ + cmcd?: Cmcd + + /** + * Any custom data. + */ + customData?: any +} diff --git a/lib/src/request/CommonMediaResponse.ts b/lib/src/request/CommonMediaResponse.ts new file mode 100644 index 00000000..906feb94 --- /dev/null +++ b/lib/src/request/CommonMediaResponse.ts @@ -0,0 +1,57 @@ +import { CommonMediaRequest } from './CommonMediaRequest.js'; +import { ResourceTiming } from './ResourceTiming.js'; + +/** + * Common response API. + * + * @group Request + * + * @beta + */ + +export interface CommonMediaResponse { + /** + * The origin request. + */ + request: CommonMediaRequest + + /** + * The final URL obtained after any redirects. + */ + url?: string + + /** + * Indicates whether or not the request was redirected. + */ + redirected?: boolean + + /** + * The HTTP status code of the response. + */ + status?: number + + /** + * The status message corresponding to the HTTP status code. + */ + statusText?: string + + /** + * The type of the response. + */ + type?: string + + /** + * The response headers. + */ + headers?: Record + + /** + * The response data. + */ + data?: any + + /** + * The network timing of the request/response. + */ + resourceTiming: ResourceTiming +} diff --git a/lib/src/request/RequestInterceptor.ts b/lib/src/request/RequestInterceptor.ts new file mode 100644 index 00000000..6a4513dd --- /dev/null +++ b/lib/src/request/RequestInterceptor.ts @@ -0,0 +1,12 @@ +import { CommonMediaRequest } from './CommonMediaRequest.js'; + +/** + * Request interceptor API. + * @param request - The request to be executed. + * @returns A promise with updated request that is resolved when the interceptor has completed the process of the request. + * + * @group Request + * + * @beta + */ +export type RequestInterceptor = (request: CommonMediaRequest) => Promise diff --git a/lib/src/request/ResourceTiming.ts b/lib/src/request/ResourceTiming.ts new file mode 100644 index 00000000..b4dad5b3 --- /dev/null +++ b/lib/src/request/ResourceTiming.ts @@ -0,0 +1,23 @@ +/** + * Resource Timing. + * + * @group Request + * + * @beta + */ +export interface ResourceTiming { + // The timestamp for the time a resource fetch started. + startTime: number + + // The size (in octets) of the payload body before removing any applied content encodings. + encodedBodySize: number + + // The timestamp immediately after the browser receives the first byte of the response from the server. + responseStart?: number + + // The timestamp immediately after the browser receives the last byte of the resource or immediately before the transport connection is closed, whichever comes first. + responseEnd?: number + + // The difference between the responseEnd and the startTime properties. + duration?: number +} diff --git a/lib/src/request/ResponseInterceptor.ts b/lib/src/request/ResponseInterceptor.ts new file mode 100644 index 00000000..58a74238 --- /dev/null +++ b/lib/src/request/ResponseInterceptor.ts @@ -0,0 +1,12 @@ +import { CommonMediaResponse } from './CommonMediaResponse.js'; + +/** + * Response interceptor API. + * @param response - The received response. + * @returns A promise with updated response that is resolved when the interceptor has completed the process of the response. + * + * @group Request + * + * @beta + */ +export type ResponseInterceptor = (response: CommonMediaResponse) => Promise diff --git a/package.json b/package.json index 6f641791..2d9f55b2 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,9 @@ "CMSD", "RFC8941", "Structured Field Values", - "ID3" + "ID3", + "Common Media Request", + "Common Media Response" ], "scripts": { "format": "npm run lint -- --fix",