api.ts

// NOTE: GENERATED by github.com/mjl-/sherpats, DO NOT MODIFY

namespace api {

// Implementation status of a feature by an implementation.
export interface Implementation {
	ID: number
	Updated: Date
	SoftwareID: string
	FeatureID: string
	Status: Status
	Bugs: boolean  // Has known bugs
	Plugin: boolean  // If functionality is delivered by plugin.
	URL: string
	SinceVersion: string
	Notes: string
}

export interface Software {
	ID: string  // e.g. "mox" or "someSoftware", keep them valid identifiers for working in js easily.
	Created: Date
	Updated: Date
	Name: string
	URL: string
	Description: string
	OpenSource: boolean
	Maintained: boolean
	License: string
	ProgLang: string
	Distribution: boolean  // Collection of other software packages.
	Server: boolean  // Corresponds to same fields in Feature.
	Service: boolean  // Hosted service, software not necessarily available.
	Library: boolean
	Client: boolean
	Desktop: boolean
	Mobile: boolean
	Web: boolean
	Terminal: boolean
}

// Feature is something software implements. Like a standard (RFC), a small part of
// a standard, or just some behaviour the software has.
export interface Feature {
	ID: string
	Created: Date
	Updated: Date
	Title: string
	URL: string
	Description: string
	Server: boolean  // Corresponds to same fields in Software, whether they are applicable.
	Service: boolean  // Hosted service, software not necessarily available.
	Library: boolean
	Client: boolean
	Desktop: boolean
	Mobile: boolean
	Web: boolean
	Terminal: boolean
}

// State is available in JS.
export interface State {
	Software?: Software[] | null
	Features?: Feature[] | null
	Implementations?: Implementation[] | null
}

// Implementation status of a feature for software.
export enum Status {
	Unknown = "",
	NotApplicable = "n/a",
	Never = "Never",
	No = "No",
	Planned = "Planned",
	Partial = "Partial",
	Yes = "Yes",
}

export const structTypes: {[typename: string]: boolean} = {"Feature":true,"Implementation":true,"Software":true,"State":true}
export const stringsTypes: {[typename: string]: boolean} = {"Status":true}
export const intsTypes: {[typename: string]: boolean} = {}
export const types: TypenameMap = {
	"Implementation": {"Name":"Implementation","Docs":"","Fields":[{"Name":"ID","Docs":"","Typewords":["int64"]},{"Name":"Updated","Docs":"","Typewords":["timestamp"]},{"Name":"SoftwareID","Docs":"","Typewords":["string"]},{"Name":"FeatureID","Docs":"","Typewords":["string"]},{"Name":"Status","Docs":"","Typewords":["Status"]},{"Name":"Bugs","Docs":"","Typewords":["bool"]},{"Name":"Plugin","Docs":"","Typewords":["bool"]},{"Name":"URL","Docs":"","Typewords":["string"]},{"Name":"SinceVersion","Docs":"","Typewords":["string"]},{"Name":"Notes","Docs":"","Typewords":["string"]}]},
	"Software": {"Name":"Software","Docs":"","Fields":[{"Name":"ID","Docs":"","Typewords":["string"]},{"Name":"Created","Docs":"","Typewords":["timestamp"]},{"Name":"Updated","Docs":"","Typewords":["timestamp"]},{"Name":"Name","Docs":"","Typewords":["string"]},{"Name":"URL","Docs":"","Typewords":["string"]},{"Name":"Description","Docs":"","Typewords":["string"]},{"Name":"OpenSource","Docs":"","Typewords":["bool"]},{"Name":"Maintained","Docs":"","Typewords":["bool"]},{"Name":"License","Docs":"","Typewords":["string"]},{"Name":"ProgLang","Docs":"","Typewords":["string"]},{"Name":"Distribution","Docs":"","Typewords":["bool"]},{"Name":"Server","Docs":"","Typewords":["bool"]},{"Name":"Service","Docs":"","Typewords":["bool"]},{"Name":"Library","Docs":"","Typewords":["bool"]},{"Name":"Client","Docs":"","Typewords":["bool"]},{"Name":"Desktop","Docs":"","Typewords":["bool"]},{"Name":"Mobile","Docs":"","Typewords":["bool"]},{"Name":"Web","Docs":"","Typewords":["bool"]},{"Name":"Terminal","Docs":"","Typewords":["bool"]}]},
	"Feature": {"Name":"Feature","Docs":"","Fields":[{"Name":"ID","Docs":"","Typewords":["string"]},{"Name":"Created","Docs":"","Typewords":["timestamp"]},{"Name":"Updated","Docs":"","Typewords":["timestamp"]},{"Name":"Title","Docs":"","Typewords":["string"]},{"Name":"URL","Docs":"","Typewords":["string"]},{"Name":"Description","Docs":"","Typewords":["string"]},{"Name":"Server","Docs":"","Typewords":["bool"]},{"Name":"Service","Docs":"","Typewords":["bool"]},{"Name":"Library","Docs":"","Typewords":["bool"]},{"Name":"Client","Docs":"","Typewords":["bool"]},{"Name":"Desktop","Docs":"","Typewords":["bool"]},{"Name":"Mobile","Docs":"","Typewords":["bool"]},{"Name":"Web","Docs":"","Typewords":["bool"]},{"Name":"Terminal","Docs":"","Typewords":["bool"]}]},
	"State": {"Name":"State","Docs":"","Fields":[{"Name":"Software","Docs":"","Typewords":["[]","Software"]},{"Name":"Features","Docs":"","Typewords":["[]","Feature"]},{"Name":"Implementations","Docs":"","Typewords":["[]","Implementation"]}]},
	"Status": {"Name":"Status","Docs":"","Values":[{"Name":"Unknown","Value":"","Docs":""},{"Name":"NotApplicable","Value":"n/a","Docs":""},{"Name":"Never","Value":"Never","Docs":""},{"Name":"No","Value":"No","Docs":""},{"Name":"Planned","Value":"Planned","Docs":""},{"Name":"Partial","Value":"Partial","Docs":""},{"Name":"Yes","Value":"Yes","Docs":""}]},
}

export const parser = {
	Implementation: (v: any) => parse("Implementation", v) as Implementation,
	Software: (v: any) => parse("Software", v) as Software,
	Feature: (v: any) => parse("Feature", v) as Feature,
	State: (v: any) => parse("State", v) as State,
	Status: (v: any) => parse("Status", v) as Status,
}

let defaultOptions: ClientOptions = {slicesNullable: true, mapsNullable: true, nullableOptional: true}

export class Client {
	private baseURL: string
	public authState: AuthState
	public options: ClientOptions

	constructor() {
		this.authState = {}
		this.options = {...defaultOptions}
		this.baseURL = this.options.baseURL || defaultBaseURL
	}

	withAuthToken(token: string): Client {
		const c = new Client()
		c.authState.token = token
		c.options = this.options
		return c
	}

	withOptions(options: ClientOptions): Client {
		const c = new Client()
		c.authState = this.authState
		c.options = { ...this.options, ...options }
		return c
	}

	async ImplementationSet(impl: Implementation): Promise<Implementation> {
		const fn: string = "ImplementationSet"
		const paramTypes: string[][] = [["Implementation"]]
		const returnTypes: string[][] = [["Implementation"]]
		const params: any[] = [impl]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as Implementation
	}

	async ImplementationRemove(id: number): Promise<void> {
		const fn: string = "ImplementationRemove"
		const paramTypes: string[][] = [["int64"]]
		const returnTypes: string[][] = []
		const params: any[] = [id]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as void
	}

	async SoftwareCreate(s: Software): Promise<void> {
		const fn: string = "SoftwareCreate"
		const paramTypes: string[][] = [["Software"]]
		const returnTypes: string[][] = []
		const params: any[] = [s]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as void
	}

	async SoftwareUpdate(s: Software): Promise<void> {
		const fn: string = "SoftwareUpdate"
		const paramTypes: string[][] = [["Software"]]
		const returnTypes: string[][] = []
		const params: any[] = [s]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as void
	}

	async SoftwareRemove(id: string): Promise<void> {
		const fn: string = "SoftwareRemove"
		const paramTypes: string[][] = [["string"]]
		const returnTypes: string[][] = []
		const params: any[] = [id]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as void
	}

	async FeatureCreate(f: Feature): Promise<void> {
		const fn: string = "FeatureCreate"
		const paramTypes: string[][] = [["Feature"]]
		const returnTypes: string[][] = []
		const params: any[] = [f]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as void
	}

	async FeatureUpdate(f: Feature): Promise<void> {
		const fn: string = "FeatureUpdate"
		const paramTypes: string[][] = [["Feature"]]
		const returnTypes: string[][] = []
		const params: any[] = [f]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as void
	}

	async FeatureRemove(id: string): Promise<void> {
		const fn: string = "FeatureRemove"
		const paramTypes: string[][] = [["string"]]
		const returnTypes: string[][] = []
		const params: any[] = [id]
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as void
	}

	async State(): Promise<State> {
		const fn: string = "State"
		const paramTypes: string[][] = []
		const returnTypes: string[][] = [["State"]]
		const params: any[] = []
		return await _sherpaCall(this.baseURL, this.authState, { ...this.options }, paramTypes, returnTypes, fn, params) as State
	}
}

export const defaultBaseURL = (function() {
	let p = location.pathname
	if (p && p[p.length - 1] !== '/') {
		let l = location.pathname.split('/')
		l = l.slice(0, l.length - 1)
		p = '/' + l.join('/') + '/'
	}
	return location.protocol + '//' + location.host + p + 'api/'
})()

// NOTE: code below is shared between github.com/mjl-/sherpaweb and github.com/mjl-/sherpats.
// KEEP IN SYNC.

export const supportedSherpaVersion = 1

export interface Section {
	Name: string
	Docs: string
	Functions: Function[]
	Sections: Section[]
	Structs: Struct[]
	Ints: Ints[]
	Strings: Strings[]
	Version: string // only for top-level section
	SherpaVersion: number // only for top-level section
	SherpadocVersion: number // only for top-level section
}

export interface Function {
	Name: string
	Docs: string
	Params: Arg[]
	Returns: Arg[]
}

export interface Arg {
	Name: string
	Typewords: string[]
}

export interface Struct {
	Name: string
	Docs: string
	Fields: Field[]
}

export interface Field {
	Name: string
	Docs: string
	Typewords: string[]
}

export interface Ints {
	Name: string
	Docs: string
	Values: {
		Name: string
		Value: number
		Docs: string
	}[] | null
}

export interface Strings {
	Name: string
	Docs: string
	Values: {
		Name: string
		Value: string
		Docs: string
	}[] | null
}

export type NamedType = Struct | Strings | Ints
export type TypenameMap = { [k: string]: NamedType }

// verifyArg typechecks "v" against "typewords", returning a new (possibly modified) value for JSON-encoding.
// toJS indicate if the data is coming into JS. If so, timestamps are turned into JS Dates. Otherwise, JS Dates are turned into strings.
// allowUnknownKeys configures whether unknown keys in structs are allowed.
// types are the named types of the API.
export const verifyArg = (path: string, v: any, typewords: string[], toJS: boolean, allowUnknownKeys: boolean, types: TypenameMap, opts: ClientOptions): any => {
	return new verifier(types, toJS, allowUnknownKeys, opts).verify(path, v, typewords)
}

export const parse = (name: string, v: any): any => verifyArg(name, v, [name], true, false, types, defaultOptions)

class verifier {
	constructor(private types: TypenameMap, private toJS: boolean, private allowUnknownKeys: boolean, private opts: ClientOptions) {
	}

	verify(path: string, v: any, typewords: string[]): any {
		typewords = typewords.slice(0)
		const ww = typewords.shift()

		const error = (msg: string) => {
			if (path != '') {
				msg = path + ': ' + msg
			}
			throw new Error(msg)
		}

		if (typeof ww !== 'string') {
			error('bad typewords')
			return // should not be necessary, typescript doesn't see error always throws an exception?
		}
		const w: string = ww

		const ensure = (ok: boolean, expect: string): any => {
			if (!ok) {
				error('got ' + JSON.stringify(v) + ', expected ' + expect)
			}
			return v
		}

		switch (w) {
		case 'nullable':
			if (v === null || v === undefined && this.opts.nullableOptional) {
				return v
			}
			return this.verify(path, v, typewords)
		case '[]':
			if (v === null && this.opts.slicesNullable || v === undefined && this.opts.slicesNullable && this.opts.nullableOptional) {
				return v
			}
			ensure(Array.isArray(v), "array")
			return v.map((e: any, i: number) => this.verify(path + '[' + i + ']', e, typewords))
		case '{}':
			if (v === null && this.opts.mapsNullable || v === undefined && this.opts.mapsNullable && this.opts.nullableOptional) {
				return v
			}
			ensure(v !== null || typeof v === 'object', "object")
			const r: any = {}
			for (const k in v) {
				r[k] = this.verify(path + '.' + k, v[k], typewords)
			}
			return r
		}

		ensure(typewords.length == 0, "empty typewords")
		const t = typeof v
		switch (w) {
		case 'any':
			return v
		case 'bool':
			ensure(t === 'boolean', 'bool')
			return v
		case 'int8':
		case 'uint8':
		case 'int16':
		case 'uint16':
		case 'int32':
		case 'uint32':
		case 'int64':
		case 'uint64':
			ensure(t === 'number' && Number.isInteger(v), 'integer')
			return v
		case 'float32':
		case 'float64':
			ensure(t === 'number', 'float')
			return v
		case 'int64s':
		case 'uint64s':
			ensure(t === 'number' && Number.isInteger(v) || t === 'string', 'integer fitting in float without precision loss, or string')
			return '' + v
		case 'string':
			ensure(t === 'string', 'string')
			return v
		case 'timestamp':
			if (this.toJS) {
				ensure(t === 'string', 'string, with timestamp')
				const d = new Date(v)
				if (d instanceof Date && !isNaN(d.getTime())) {
					return d
				}
				error('invalid date ' + v)
			} else {
				ensure(t === 'object' && v !== null, 'non-null object')
				ensure(v.__proto__ === Date.prototype, 'Date')
				return v.toISOString()
			}
		}

		// We're left with named types.
		const nt = this.types[w]
		if (!nt) {
			error('unknown type ' + w)
		}
		if (v === null) {
			error('bad value ' + v + ' for named type ' + w)
		}

		if (structTypes[nt.Name]) {
			const t = nt as Struct
			if (typeof v !== 'object') {
				error('bad value ' + v + ' for struct ' + w)
			}

			const r: any = {}
			for (const f of t.Fields) {
				r[f.Name] = this.verify(path + '.' + f.Name, v[f.Name], f.Typewords)
			}
			// If going to JSON also verify no unknown fields are present.
			if (!this.allowUnknownKeys) {
				const known: { [key: string]: boolean } = {}
				for (const f of t.Fields) {
					known[f.Name] = true
				}
				Object.keys(v).forEach((k) => {
					if (!known[k]) {
						error('unknown key ' + k + ' for struct ' + w)
					}
				})
			}
			return r
		} else if (stringsTypes[nt.Name]) {
			const t = nt as Strings
			if (typeof v !== 'string') {
				error('mistyped value ' + v + ' for named strings ' + t.Name)
			}
			if (!t.Values || t.Values.length === 0) {
				return v
			}
			for (const sv of t.Values) {
				if (sv.Value === v) {
					return v
				}
			}
			error('unknkown value ' + v + ' for named strings ' + t.Name)
		} else if (intsTypes[nt.Name]) {
			const t = nt as Ints
			if (typeof v !== 'number' || !Number.isInteger(v)) {
				error('mistyped value ' + v + ' for named ints ' + t.Name)
			}
			if (!t.Values || t.Values.length === 0) {
				return v
			}
			for (const sv of t.Values) {
				if (sv.Value === v) {
					return v
				}
			}
			error('unknkown value ' + v + ' for named ints ' + t.Name)
		} else {
			throw new Error('unexpected named type ' + nt)
		}
	}
}


export interface ClientOptions {
	baseURL?: string
	aborter?: {abort?: () => void}
	timeoutMsec?: number
	skipParamCheck?: boolean
	skipReturnCheck?: boolean
	slicesNullable?: boolean
	mapsNullable?: boolean
	nullableOptional?: boolean
	csrfHeader?: string
	login?: (reason: string) => Promise<string>
}

export interface AuthState {
	token?: string // For csrf request header.
	loginPromise?: Promise<void> // To let multiple API calls wait for a single login attempt, not each opening a login popup.
}

const _sherpaCall = async (baseURL: string, authState: AuthState, options: ClientOptions, paramTypes: string[][], returnTypes: string[][], name: string, params: any[]): Promise<any> => {
	if (!options.skipParamCheck) {
		if (params.length !== paramTypes.length) {
			return Promise.reject({ message: 'wrong number of parameters in sherpa call, saw ' + params.length + ' != expected ' + paramTypes.length })
		}
		params = params.map((v: any, index: number) => verifyArg('params[' + index + ']', v, paramTypes[index], false, false, types, options))
	}
	const simulate = async (json: string) => {
		const config = JSON.parse(json || 'null') || {}
		const waitMinMsec = config.waitMinMsec || 0
		const waitMaxMsec = config.waitMaxMsec || 0
		const wait = Math.random() * (waitMaxMsec - waitMinMsec)
		const failRate = config.failRate || 0
		return new Promise<void>((resolve, reject) => {
			if (options.aborter) {
				options.aborter.abort = () => {
					reject({ message: 'call to ' + name + ' aborted by user', code: 'sherpa:aborted' })
					reject = resolve = () => { }
				}
			}
			setTimeout(() => {
				const r = Math.random()
				if (r < failRate) {
					reject({ message: 'injected failure on ' + name, code: 'server:injected' })
				} else {
					resolve()
				}
				reject = resolve = () => { }
			}, waitMinMsec + wait)
		})
	}
	// Only simulate when there is a debug string. Otherwise it would always interfere
	// with setting options.aborter.
	let json: string = ''
	try {
		json = window.localStorage.getItem('sherpats-debug') || ''
	} catch (err) {}
	if (json) {
		await simulate(json)
	}

	const fn = (resolve: (v: any) => void, reject: (v: any) => void) => {
		let resolve1 = (v: any) => {
			resolve(v)
			resolve1 = () => { }
			reject1 = () => { }
		}
		let reject1 = (v: { code: string, message: string }) => {
			if ((v.code === 'user:noAuth' || v.code === 'user:badAuth')  && options.login) {
				const login = options.login
				if (!authState.loginPromise) {
					authState.loginPromise = new Promise((aresolve, areject) => {
						login(v.code === 'user:badAuth' ? (v.message || '') : '')
						.then((token) => {
							authState.token = token
							authState.loginPromise = undefined
							aresolve()
						}, (err: any) => {
							authState.loginPromise = undefined
							areject(err)
						})
					})
				}
				authState.loginPromise
				.then(() => {
					fn(resolve, reject)
				}, (err: any) => {
					reject(err)
				})
				return
			}
			reject(v)
			resolve1 = () => { }
			reject1 = () => { }
		}

		const url = baseURL + name
		const req = new window.XMLHttpRequest()
		if (options.aborter) {
			options.aborter.abort = () => {
				req.abort()
				reject1({ code: 'sherpa:aborted', message: 'request aborted' })
			}
		}
		req.open('POST', url, true)
		if (options.csrfHeader && authState.token) {
			req.setRequestHeader(options.csrfHeader, authState.token)
		}
		if (options.timeoutMsec) {
			req.timeout = options.timeoutMsec
		}
		req.onload = () => {
			if (req.status !== 200) {
				if (req.status === 404) {
					reject1({ code: 'sherpa:badFunction', message: 'function does not exist' })
				} else {
					reject1({ code: 'sherpa:http', message: 'error calling function, HTTP status: ' + req.status })
				}
				return
			}

			let resp: any
			try {
				resp = JSON.parse(req.responseText)
			} catch (err) {
				reject1({ code: 'sherpa:badResponse', message: 'bad JSON from server' })
				return
			}
			if (resp && resp.error) {
				const err = resp.error
				reject1({ code: err.code, message: err.message })
				return
			} else if (!resp || !resp.hasOwnProperty('result')) {
				reject1({ code: 'sherpa:badResponse', message: "invalid sherpa response object, missing 'result'" })
				return
			}

			if (options.skipReturnCheck) {
				resolve1(resp.result)
				return
			}
			let result = resp.result
			try {
				if (returnTypes.length === 0) {
					if (result) {
						throw new Error('function ' + name + ' returned a value while prototype says it returns "void"')
					}
				} else if (returnTypes.length === 1) {
					result = verifyArg('result', result, returnTypes[0], true, true, types, options)
				} else {
					if (result.length != returnTypes.length) {
						throw new Error('wrong number of values returned by ' + name + ', saw ' + result.length + ' != expected ' + returnTypes.length)
					}
					result = result.map((v: any, index: number) => verifyArg('result[' + index + ']', v, returnTypes[index], true, true, types, options))
				}
			} catch (err) {
				let errmsg = 'bad types'
				if (err instanceof Error) {
					errmsg = err.message
				}
				reject1({ code: 'sherpa:badTypes', message: errmsg })
			}
			resolve1(result)
		}
		req.onerror = () => {
			reject1({ code: 'sherpa:connection', message: 'connection failed' })
		}
		req.ontimeout = () => {
			reject1({ code: 'sherpa:timeout', message: 'request timeout' })
		}
		req.setRequestHeader('Content-Type', 'application/json')
		try {
			req.send(JSON.stringify({ params: params }))
		} catch (err) {
			reject1({ code: 'sherpa:badData', message: 'cannot marshal to JSON' })
		}
	}
	return await new Promise(fn)
}

}