This package has been deprecated

Author message:

This package is intended for testing purposes only.

@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

We have introduced the utils.Date object to replace the Date implementation and ignore the timezone. As we need to get rid of the timezones more often than not, this will be our default behavior. By default, the Date models are replaced with utils.Date.

When we need to keep the timezone information, we create a new field directly in the SDK. As this field does not exist in the specification, it will not be part of the base model but of the core model instead.

Simple example:

  Flight:
    type: "object"
    required:
      - departureDateTime
    properties:
      departureDateTime:
        type: string
        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.

How to keep the timezone (prevent Date replacement with utils.Date)

In order to add the timezone to your timestamp property you can add the x-date-timezone extension in your yaml, for example:

properties:
  timestamp:
    title: timestamp
    description: >-
      Timestamp when event is triggered. UTC time (server time), with a
      format similar to yyyy-MM-ddThh:mm:ss.sTZD. Refer to the pattern
    type: string
    format: date-time
    x-date-timezone:
      description: If this vendor extension is present send dates with the timezone
    pattern: >-
      ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{1,3}([Z]|([+][0-9]{2}:?[0-9]{2}$))
    example: '2013-12-31T19:20:30.45+01:00'