@ama-sdk/showcase-sdk

Showcase SDK

Note: This package is intended for testing purposes only. It is not suitable for production use.

Based on openapi specs 3.0.2

The SDK contains 2 different parts:

• Auto generated code (based on Swagger Spec)
• Specific code dedicated to this SDK

Structure

Auto Generated code

A main part of the SDK is automatically generated from a Swagger Spec. The following folders contain the generated code:

• src/api: Containing the API calls files
• src/models/base: Models based of swagger definitions

The Code can be regenerated by running the following command:

yarn schematics @ama-sdk/sdk:typescript-core --spec-path [path to your swagger file]

Note that you can use npm exec instead of yarn for every command specified in this documentation.

Where to put my custom code?

There are 2 places where we can add custom code:

• src/helpers: should contain the helper functions to transform the data.
• src/models/custom: should contain the models specific to this SDK (mainly the helper functions return type).

How to extend a Model?

You can extend a base model in 3 steps:

• Redirect the default model to your override:

// src/models/base/<model name>/index.ts
export * from "../../core/<model name>";

• Indicate to Swagger CodeGen that you have override the base model:

# in .swagger-codegen-ignore
src/models/base/<model name>/index.ts

• Create your core models

// src/models/core/<model name>/index.ts
export * from "./<model name>.ts";
export * from "./<model name>.reviver.ts";

// src/models/core/<model name>/<model name>.ts
import { <model name> as Base<model name> } from "../../base/<model name>/<model name>";

export interface <model name> extends BaseB<model name> {
  // Additional fields
}

// src/models/core/<model name>/<model name>.reviver.ts
import { yourFunction } from "../../../helpers/<model name>";
import { revive<model name> as Base<model name> } from "../../base/<model name>/<model name>.reviver";
import { <model name> } from "./<model name>";

import {Reviver, utils} from "@ama-sdk/core";

export function revive<model name><T extends <model name> = <model name>>(data: any, dictionary?: any) {
  // TODO: use BaseRevive<T> when ready
  const revivedData: T | undefined = Base<model name>(data, dictionary) as T | undefined;

  if (!revivedData) { return ; }

  if (!revivedData.yourField) {
    revivedData.yourField = yourFunction(revivedData);
  }

  return revivedData;
}

Commands

Some commands are provided to keep your SDK up-to-date.

Generate SDK from a Swagger specification

yarn spec:regen

Run Unit Tests

You can build and run UT with:

yarn test

Manage dates

The timezone issue

Managing dates with timezones has always been a bit painful in front end applications. Let's give a concrete example to understand the problem: An API returns the date and hour of your flight in the timezone of the airport location. In our use case, let's say the departure airport is on GTM+7 : 2023-07-10T00:37:00.000+07:00. The timezone sent is the one from the airport, here GMT+7. If you just use the Date(), the computer browser will convert this in its own timezone. For example, if the user is in GMT+2 you will end up displaying the following: 2023-07-09T19:37:00.000+02:00. This is not what you want. You want the exact date time of the flight at the airport timezone, not the one of your user's computer. However, there might be cases where you might still need the timezone information. For example, you want to be able to display that the flight is in X hours. You will need to compute this information with the two timezones -- the airport's and the user's.

Solution proposed to remove the timezone: utils.DateTime

The Otter framework has introduced the utils.Date and utils.DateTime objects to replace the Date implementation and convert the date returned by the API as if it were in the timezone of the user.

Dates can be generated as utils.Date or string depending on the value of the stringifyDate option. This ensures that the timezone will not impact the date. In the case of date-time object, the default type used is string or native Date depending on the stringifyDate option value.

If you want to generate a date-time using utils.DateTime, you can do it at property level thanks to the x-local-timezone vendor. As this field does not exist in the specification, it will not be part of the base model but of the core model instead (the first one being completely generated from the API specifications).

Simple example:

  Flight:
    type: "object"
    required:
      - departureDateTime
    properties:
      departureDateTime:
        type: string
        x-local-timezone: true
        description: If this vendor extension is present send dates without their timezone
        format: date-time

Base model generated

// flight.ts generated in base models
export interface Flight {
  /** @see utils.DateTime */
  departureDateTime: utils.DateTime;
}

You need to create a core model to store the timezone information (src/models/core/flight.ts):

import type { IgnoreEnum } from '@ama-sdk/core';
import type { Flight } from '../../base/flight/flight';
export type FlightStopCoreIfy<T extends IgnoreEnum<Flight>> = T & {
  /** Departure date time of the flight considering timezone */
  departureDateTimeConsideringTimezone?: Date;
};

And an associated reviver (src/models/core/flight.reviver.ts):

import type { Flight } from '../../base/flight/flight';
import type { reviveFlight } from '../../base/flight/flight.reviver';
import type { FlightCoreIfy } from './flight';

/**
 * @param baseRevive
 */
export function reviveFlightFactory<R extends typeof reviveFlight>(baseRevive: R) {
  const reviver = <T extends Flight = Flight>(data: any, dictionaries?: any) => {
    const originalData: any = {...data};
    const revivedData = baseRevive<FlightCoreIfy<T>>(data, dictionaries);
    if (!revivedData) {
      return;
    }
    revivedData.departureDateTimeConsideringTimezone = originalData.departureDateTimeConsideringTimezone && new Date(originalData.departureDateTimeConsideringTimezone)
      || originalData.departureDateTime && new Date(originalData.departureDateTime);
    return revivedData;
  };
  return reviver;
}

And export it here (src/models/core/flight/index.ts):

export * from './flight';
export * from './flight.reviver';

And here (src/models/core/index.ts):

export * from './flight/index';

You can now use departureDateTimeConsideringTimezone to access the timezone information. See utils.Date for more information.